Quickstart

This guide walks you through the complete process of converting USD to Bitcoin and sending it to a Spark wallet using just-in-time (JIT) funding.

Prerequisites

Before starting this guide, ensure you have:

A Grid API account with valid authentication credentials
Access to the Grid API endpoints (production or sandbox)
A webhook endpoint configured to receive notifications
A Spark wallet address where the Bitcoin will be delivered

Overview

The on-ramp process consists of the following steps:

Create a customer via the API
Create a quote for the USD-to-BTC conversion with current exchange rate
Fund the quote using the provided payment instructions (JIT funding)
Receive webhook notification confirming Bitcoin delivery to the Spark wallet

Step 1: Customer Onboarding

If your platform is a regulated financial institution that already has a KYC/KYB process in place, you can create a customer directly via the API. However, if your platform is not regulated, you must use the hosted KYC/KYB link flow to onboard your customers.

Regulated Platforms
Unregulated Platforms

Regulated platforms have lighter KYC requirements since they handle compliance verification internally.

The KYC/KYB flow allows you to onboard customers through direct API calls.Regulated financial institutions can:

Direct API Onboarding: Create customers directly via API calls with minimal verification
Internal KYC/KYB: Handle identity verification through your own compliance systems
Reduced Documentation: Only provide essential customer information required by your payment counterparty or service provider.
Faster Onboarding: Streamlined process for known, verified customers

Creating Customers via Direct API

For regulated platforms, you can create customers directly through the API without requiring external KYC verification:To register a new customer in the system, use the POST /customers endpoint:

curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers" \
  -H "Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "platformCustomerId": "customer_12345",
    "customerType": "INDIVIDUAL",
    "fullName": "Jane Doe",
    "birthDate": "1992-03-25",
    "nationality": "US",
    "address": {
      "line1": "123 Pine Street",
      "city": "Seattle",
      "state": "WA",
      "postalCode": "98101",
      "country": "US"
    }
  }'

The examples below show a more comprehensive set of data. Not all fields are strictly required by the API for customer creation itself, but become necessary based on currency and UMA provider requirements if using UMA.

Individual customer
Business Customer

{
  "platformCustomerId": "9f84e0c2a72c4fa",
  "customerType": "INDIVIDUAL",
  "fullName": "John Sender",
  "birthDate": "1985-06-15",
  "address": {
    "line1": "Paseo de la Reforma 222",
    "line2": "Piso 15",
    "city": "Ciudad de México",
    "state": "Ciudad de México",
    "postalCode": "06600",
    "country": "MX"
  }
}

Step 2: Create a Quote for Fiat-to-Crypto Conversion

Create a quote to convert USD to Bitcoin and deliver it to a Spark wallet. The quote will provide the current exchange rate and payment instructions for funding.

Request

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": {
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "currency": "USD"
    },
    "destination": {
      "externalAccountDetails": {
        "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
        "currency": "BTC",
        "accountInfo": {
          "accountType": "SPARK_WALLET",
          "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu"
        }
      }
    },
    "lockedCurrencySide": "SENDING",
    "lockedCurrencyAmount": 10000,
    "description": "On-ramp: Buy $100 of Bitcoin"
  }'

Combined External Account Creation: The externalAccountDetails option automatically creates the external account (Spark wallet) and uses it as the destination for the Bitcoin transfer in a single API call. If you want to reuse the same external accounts for many quotes, you can add them using the /external-accounts endpoint, and then use the accountId in the quote creation request.

Response

{
  "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
  "status": "PENDING",
  "createdAt": "2025-10-03T15:00:00Z",
  "expiresAt": "2025-10-03T15:05:00Z",
  "source": {
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "currency": "USD"
  },
  "destination": {
    "accountId": "ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456",
    "currency": "BTC"
  },
  "sendingCurrency": {
    "code": "USD",
    "name": "United States Dollar",
    "symbol": "$",
    "decimals": 2
  },
  "receivingCurrency": {
    "code": "BTC",
    "name": "Bitcoin",
    "symbol": "₿",
    "decimals": 8
  },
  "totalSendingAmount": 10000,
  "totalReceivingAmount": 83333,
  "exchangeRate": 8.3333,
  "feesIncluded": 250,
  "paymentInstructions": [
    {
      "instructionsNotes": "Include reference code in transfer memo",
      "accountOrWalletInfo": {
        "reference": "RAMP-ABC123",
        "accountType": "US_ACCOUNT",
        "accountNumber": "9876543210",
        "routingNumber": "021000021",
        "accountHolderName": "Lightspark Payments FBO Customer",
        "bankName": "JP Morgan Chase"
      }
    },
    {
      "accountOrWalletInfo": {
        "accountType": "SOLANA_WALLET",
        "assetType": "USDC",
        "address": "4Nd1m6Qkq7RfKuE5vQ9qP9Tn6H94Ueqb4xXHzsAbd8Wg"
      }
    }
  ]
}

The quote shows:

Sending: $100.00 USD (including $2.50 fee)
Receiving: 0.00083333 BTC (83,333 satoshis)
Exchange rate: 8.3333 sats per USD cent (~$120,000 per BTC)
Quote expires: In 5 minutes
Payment instructions: Bank account details and reference code for funding

For JIT-funded quotes, do NOT call the /quotes/{quoteId}/execute endpoint. Simply fund using the payment instructions, and Grid will automatically execute the conversion upon receiving your payment. The execute endpoint is used for quotes with an internal account or pullable external account as the source.

Step 3: Fund the Quote (Just-in-Time)

In production, you would initiate a real-time push payment (ACH, RTP, wire, etc.) to the bank account provided in paymentInstructions, making sure to include the exact reference code RAMP-ABC123 in the transfer memo.

Sandbox (Simulated)
Production (Real Funding)

In Sandbox, you can simulate funding using the /sandbox/send endpoint:

curl -X POST "https://api.lightspark.com/grid/2025-10-13/sandbox/send" \
  -H "Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "RAMP-ABC123",
    "currencyCode": "USD",
    "currencyAmount": 10000
  }'

Response:

{
  "id": "Transaction:019542f5-b3e7-1d02-0000-000000000025",
  "status": "PROCESSING",
  "type": "OUTGOING",
  "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006"
}

The reference code is critical for matching your payment to the quote. Always include it exactly as provided in the payment instructions.

Step 4: Receive Completion Webhook

Once Grid receives your payment and completes the USD-to-BTC conversion and delivery, you’ll receive a webhook notification:

{
  "transaction": {
    "id": "Transaction:019542f5-b3e7-1d02-0000-000000000025",
    "status": "COMPLETED",
    "type": "OUTGOING",
    "sentAmount": {
      "amount": 10000,
      "currency": {
        "code": "USD",
        "name": "United States Dollar",
        "symbol": "$",
        "decimals": 2
      }
    },
    "receivedAmount": {
      "amount": 83333,
      "currency": {
        "code": "BTC",
        "name": "Bitcoin",
        "symbol": "₿",
        "decimals": 8
      }
    },
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "settledAt": "2025-10-03T15:02:30Z",
    "createdAt": "2025-10-03T15:00:00Z",
    "description": "On-ramp: Buy $100 of Bitcoin",
    "exchangeRate": 8.3333,
    "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
    "paymentInstructions": [
      {
        "instructionsNotes": "Include reference code in transfer memo",
        "accountOrWalletInfo": {
          "accountType": "US_ACCOUNT",
          "accountNumber": "1234567890",
          "routingNumber": "021000021",
          "bankName": "Chase Bank",
          "referenceCode": "REF123456"
        }
      }
    ]
  },
  "timestamp": "2025-10-03T15:03:00Z",
  "webhookId": "Webhook:019542f5-b3e7-1d02-0000-000000000030",
  "type": "OUTGOING_PAYMENT"
}

The customer now has 83,333 satoshis (0.00083333 BTC) in their Spark wallet!

Summary

You’ve successfully completed a fiat-to-crypto on-ramp! Here’s what happened:

✅ Created a customer via API
✅ Created a quote with exchange rate and payment instructions
✅ Funded the quote using JIT payment (simulated in sandbox)
✅ Bitcoin automatically converted and delivered to Spark wallet

Next Steps

Off-ramps: Learn how to convert crypto to fiat in the Crypto-to-Fiat guide
Self-custody wallets: Explore advanced wallet integration in the Self-Custody Wallets guide
Webhook verification: Implement signature verification for security (see Webhooks guide)
Sandbox testing: Learn more about testing in the Sandbox Testing guide

API Reference - Complete API documentation
Implementation Overview - High-level architecture and flow
Platform Configuration - Configure your platform settings

Onboarding

Managing Accounts

Conversion Flows

Platform Tools

Prerequisites

Overview

Step 1: Customer Onboarding

Creating Customers via Direct API

Step 2: Create a Quote for Fiat-to-Crypto Conversion

Request

Response

Step 3: Fund the Quote (Just-in-Time)

Step 4: Receive Completion Webhook

Summary

Next Steps

Onboarding

Managing Accounts

Conversion Flows

Platform Tools

​Prerequisites

​Overview

​Step 1: Customer Onboarding

​Creating Customers via Direct API

​Step 2: Create a Quote for Fiat-to-Crypto Conversion

​Request

​Response

​Step 3: Fund the Quote (Just-in-Time)

​Step 4: Receive Completion Webhook

​Summary

​Next Steps

​Related Resources

Prerequisites

Overview

Step 1: Customer Onboarding

Creating Customers via Direct API

Step 2: Create a Quote for Fiat-to-Crypto Conversion

Request

Response

Step 3: Fund the Quote (Just-in-Time)

Step 4: Receive Completion Webhook

Summary

Next Steps

Related Resources