Fiat-to-Crypto and Crypto-to-Fiat

Overview

Grid enables seamless conversion between fiat currencies and cryptocurrencies via the Lightning Network. Use quotes to lock exchange rates and get payment instructions for completing transfers. On-ramp (Fiat → Crypto): User sends fiat → Grid detects payment → Crypto sent to wallet Off-ramp (Crypto → Fiat): Execute quote → Grid processes crypto → Fiat sent to bank

Prerequisites

Customer created in Grid
On-ramps: Destination crypto wallet (Spark address) + webhook endpoint
Off-ramps: Internal account with crypto + external bank account registered

On-ramp: Fiat to crypto

Create a quote

First, create an external account for the crypto destination:

cURL

curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers/external-accounts' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "currency": "BTC",
    "accountInfo": {
      "accountType": "SPARK_WALLET",
      "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu"
    }
  }'

Then create a quote using the external account ID:

cURL

curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "source": {
      "sourceType": "REALTIME_FUNDING",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "currency": "USD"
    },
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456"
    },
    "lockedCurrencySide": "RECEIVING",
    "lockedCurrencyAmount": 100000,
    "description": "Buy 0.001 BTC"
  }'

Response includes payment instructions:

{
  "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
  "status": "PENDING",
  "createdAt": "2025-10-03T12:00:00Z",
  "expiresAt": "2025-10-03T12:05:00Z",
  "source": {
    "sourceType": "REALTIME_FUNDING",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "currency": "USD"
  },
  "destination": {
    "destinationType": "ACCOUNT",
    "accountId": "ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456"
  },
  "sendingCurrency": { "code": "USD", "name": "United States Dollar", "symbol": "$", "decimals": 2 },
  "receivingCurrency": { "code": "BTC", "name": "Bitcoin", "symbol": "₿", "decimals": 8 },
  "totalSendingAmount": 6500,
  "totalReceivingAmount": 100000,
  "exchangeRate": 15.38,
  "feesIncluded": 200,
  "transactionId": "Transaction:019542f5-b3e7-1d02-0000-000000000007",
  "paymentInstructions": [
    {
      "accountOrWalletInfo": {
        "accountType": "US_ACCOUNT",
        "reference": "UMA-Q12345-REF",
        "accountNumber": "1234567890",
        "routingNumber": "021000021",
        "bankName": "Grid Settlement Bank"
      }
    },
    {
      "accountOrWalletInfo": {
        "accountType": "SOLANA_WALLET",
        "assetType": "USDC",
        "address": "4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8Wg"
      }
    }
  ]
}

Display payment instructions

function displayPaymentInstructions(quote) {
  // EU customers only: an SCA-gated realtime-funding quote comes back
  // PENDING_AUTHORIZATION with paymentInstructions withheld until its
  // scaChallenge is authorized (see "Strong Customer Authentication" below).
  // Authorize first, then display — don't read paymentInstructions while pending.
  if (!quote.paymentInstructions?.length) {
    return { pendingAuthorization: true, scaChallenge: quote.scaChallenge };
  }

  const instructions = quote.paymentInstructions[0];

  return {
    amount: `$${(quote.totalSendingAmount / 100).toFixed(2)}`,
    bankName: instructions.accountOrWalletInfo.bankName,
    accountNumber: instructions.accountOrWalletInfo.accountNumber,
    routingNumber: instructions.accountOrWalletInfo.routingNumber,
    referenceCode: instructions.accountOrWalletInfo.reference, // User must include this
    expiresAt: quote.expiresAt,
    willReceive: `${quote.totalReceivingAmount / 100000000} BTC`,
  };
}

Monitor completion

Grid sends OUTGOING_PAYMENT.<STATUS> webhooks as the transaction progresses:

app.post("/webhooks/grid", async (req, res) => {
  const { type, data } = req.body;

  if (type === "OUTGOING_PAYMENT.COMPLETED") {
    await notifyUser(data.customerId, {
      message: "Your Bitcoin purchase is complete!",
      amount: `${data.receivedAmount.amount / 100000000} BTC`,
    });
  } else if (type === "OUTGOING_PAYMENT.FAILED") {
    await notifyUser(data.customerId, {
      message: `Purchase failed: ${data.failureReason}`,
    });
    // Refund webhook (OUTGOING_PAYMENT.REFUND_*) will follow
  }

  res.status(200).json({ received: true });
});

See the Transaction Lifecycle guide for all status transitions and refund handling.

Off-ramp: Crypto to fiat

Create and execute a quote

// 1. Create quote
const quote = await fetch("https://api.lightspark.com/grid/2025-10-13/quotes", {
  method: "POST",
  body: JSON.stringify({
    source: {
      sourceType: "ACCOUNT",
      accountId: "InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123",
    },
    destination: {
      destinationType: "ACCOUNT",
      accountId: "ExternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    },
    lockedCurrencySide: "SENDING",
    lockedCurrencyAmount: 100000, // 0.001 BTC
    description: "Sell 0.001 BTC",
  }),
}).then((r) => r.json());

// 2. Execute quote
const result = await fetch(
  `https://api.lightspark.com/grid/2025-10-13/quotes/${quote.id}/execute`,
  {
    method: "POST",
    headers: { Authorization: `Basic ${credentials}` },
  }
).then((r) => r.json());

Track completion

app.post("/webhooks/grid", async (req, res) => {
  const { type, data } = req.body;

  if (type === "OUTGOING_PAYMENT.COMPLETED") {
    await notifyUser(data.customerId, {
      message: "Your USD withdrawal is complete!",
      amount: `$${data.receivedAmount.amount / 100}`,
    });
  } else if (type === "OUTGOING_PAYMENT.FAILED") {
    await notifyUser(data.customerId, {
      message: `Withdrawal failed: ${data.failureReason}`,
    });
  }

  res.status(200).json({ received: true });
});

Immediate execution

For instant on-ramps (e.g., reward payouts), use immediatelyExecute: true with an internal account source:

cURL

curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes' \
  -H 'Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "source": {
      "sourceType": "ACCOUNT",
      "accountId": "InternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
    },
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456"
    },
    "lockedCurrencySide": "RECEIVING",
    "lockedCurrencyAmount": 100000,
    "immediatelyExecute": true
  }'

immediatelyExecute can only be used with sources that are either internal accounts or external accounts with direct pull functionality (e.g., ACH pull).

Strong Customer Authentication (EU customers)

Customers in SCA-regulated regions (in practice the EU: EUR / USDC) must confirm money movements with Strong Customer Authentication, and a conversion out of EUR / USDC is gated on its swap leg. When it applies, the transaction comes back PENDING_AUTHORIZATION with an scaChallenge that you authorize before the conversion is released; for every other customer nothing changes. See Per-transaction authorization for the full walkthrough.

Best practices

Handle quote expiration

async function refreshQuoteIfNeeded(quote) {
  const expiresAt = new Date(quote.expiresAt);
  const now = new Date();

  if (expiresAt - now < 60000) {
    // Less than 1 minute left
    return await createNewQuote(quote.originalParams);
  }

  return quote;
}

Settlement times by payment rail

const settlementTimes = {
  US_ACCOUNT: "1-3 business days (ACH)",
  WIRE: "Same day",
  SPARK_WALLET: "Instant",
  PIX: "Instant",
  SEPA: "1-2 business days",
};

Handle failed transactions

if (transaction.status === "FAILED") {
  await notifyUser(transaction.customerId, {
    message: "Transaction failed",
    reason: transaction.failureReason,
    action: "retry",
  });

  if (transaction.failureReason === "QUOTE_EXPIRED") {
    await createNewQuote(transaction.originalParams);
  }
}

Overview

Onboarding

Managing accounts

Conversion flows

Global Accounts

Platform tools

Overview

Prerequisites

On-ramp: Fiat to crypto

Create a quote

Display payment instructions

Monitor completion

Off-ramp: Crypto to fiat

Create and execute a quote

Track completion

Immediate execution

Strong Customer Authentication (EU customers)

Best practices

Next steps

​Overview

​Prerequisites

​On-ramp: Fiat to crypto

​Create a quote

​Display payment instructions

​Monitor completion

​Off-ramp: Crypto to fiat

​Create and execute a quote

​Track completion

​Immediate execution

​Strong Customer Authentication (EU customers)

​Best practices

​Next steps

Overview

Prerequisites

On-ramp: Fiat to crypto

Create a quote

Display payment instructions

Monitor completion

Off-ramp: Crypto to fiat

Create and execute a quote

Track completion

Immediate execution

Strong Customer Authentication (EU customers)

Best practices

Next steps