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?

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.

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.

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 section.

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:

{
  "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:

Lock Sending Amount

Use when: Customer knows exactly how much they want to send

{
  "lockedCurrencySide": "SENDING",
  "lockedCurrencyAmount": 100000
}

Grid calculates what the recipient will receive based on current exchange rates.

Lock Receiving Amount

Use when: Recipient must receive an exact amount (e.g., invoice payment)

{
  "lockedCurrencySide": "RECEIVING",
  "lockedCurrencyAmount": 92000
}

Grid calculates how much the sender must send to ensure recipient gets exactly €920.

Funding Models

Grid supports two funding models for quotes:

Prefunded (From Internal Account)

Source is an existing internal account with available balance:

{
  "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:

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

Quote response includes payment instructions:

{
  "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:

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:

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

Execution Timing

Prefunded

• Transaction created with status PENDING
• Funds debited from source account immediately
• Settlement begins right away

JIT Funded

• Quote waits for payment receipt
• Once Grid receives payment with correct reference
• Quote executes automatically
• Transaction created and settlement begins

Immediate Execution

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

Immediate quote execution

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
  }'

Response

{
  "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"
}

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

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).

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.

Fees

All fees are transparently displayed in the quote response:

{
  "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)

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.

Best Practices

Always show the quote to customers before executing

Let customers review the exchange rate, fees, and final amounts before committing:

// ✅ 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});

Handle expiration gracefully

Store quote parameters so you can recreate expired quotes:

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);
  }
}

Monitor quote status via webhooks

Subscribe to quote-related webhooks:

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();
});