> ## Documentation Index
> Fetch the complete documentation index at: https://ramps-docs-sync-20260519.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Complete guide for converting fiat to crypto (on-ramp) and delivering Bitcoin to a Spark wallet
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:
1. **Create a customer** via the API
2. **Create an external account** for the destination Spark wallet
3. **Create a quote** for the USD-to-BTC conversion with current exchange rate
4. **Fund the quote** using the provided payment instructions (JIT funding)
5. **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** 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:
```bash theme={null}
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.
```json theme={null}
{
"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"
}
}
```
```json theme={null}
{
"platformCustomerId": "b87d2e4a9c13f5b",
"customerType": "BUSINESS",
"businessInfo": {
"legalName": "Acme Corporation",
"registrationNumber": "789012345",
"taxId": "123-45-6789"
},
"address": {
"line1": "456 Oak Avenue",
"line2": "Floor 12",
"city": "New York",
"state": "NY",
"postalCode": "10001",
"country": "US"
}
}
```
**Unregulated platforms** require full KYC/KYB verification of customers through hosted flows.
Unregulated platforms must:
* **Hosted KYC Flow**: Use the hosted KYC link for complete identity verification
* **Extended Review**: Customers may require manual review and approval in some cases
### Hosted KYC Link Flow
The hosted KYC flow provides a secure, hosted interface where customers can complete their identity verification and onboarding process.
The flow is two steps: create the customer with the information you have, then generate a hosted KYC link for that customer. The customer's `kycStatus` stays `PENDING` until they complete the hosted flow.
#### 1. Create the customer
Create the customer with `POST /customers`, supplying at least `customerType` and any fields you already have. See [Configuring Customers](/payouts-and-b2b/onboarding/configuring-customers) for the full list of optional pre-fill fields.
```bash theme={null}
curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers" \
-u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
-H "Content-Type: application/json" \
-d '{
"customerType": "INDIVIDUAL",
"platformCustomerId": "9f84e0c2a72c4fa",
"region": "US",
"currencies": ["USD", "USDC"],
"email": "jane.doe@example.com",
"fullName": "Jane Doe"
}'
```
Persist the returned `id` (the Grid customer ID) — you'll need it for the next step.
#### 2. Generate a KYC link
```bash theme={null}
curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers/Customer:019542f5-b3e7-1d02-0000-000000000001/kyc-link" \
-u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"redirectUri": "https://yourapp.com/onboarding-complete"
}'
```
**Response:**
```json theme={null}
{
"kycUrl": "https://kyc.lightspark.com/onboard/abc123def456",
"expiresAt": "2027-01-15T14:32:00Z",
"provider": "SUMSUB",
"token": "_act-sbx-jwt-eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
The response always includes `kycUrl` for the hosted flow. For providers that support direct SDK integration (currently SUMSUB), a `token` is also returned — you can pass this to the provider's web SDK to embed verification in your own UI instead of redirecting. Both paths update the customer's `kycStatus` identically.
#### Complete KYC Process
Call `POST /customers` with `customerType` and any pre-fill fields you have. The returned `id` is the customer's Grid ID; their `kycStatus` is `PENDING` until verification completes.
Call `POST /customers/{customerId}/kyc-link`. Each call returns a fresh single-use `kycUrl` and `expiresAt`; previously-issued links remain single-use but aren't invalidated.
The `redirectUri` you pass is embedded in the generated `kycUrl` and is used to automatically return the customer to your application after they complete verification.
Redirect the customer to `kycUrl`, or — if you want to embed the flow directly — initialize the provider's SDK with the returned `token`.
The hosted URL is single-use and expires at `expiresAt`. If a customer needs to retry, call the endpoint again to generate a new link.
Reaching your `redirectUri` only means the customer **finished the hosted flow** — not that they were approved. Wait for the final decision in one of two ways:
* **Webhook (recommended):** Subscribe to `KYC_STATUS` to be notified when the customer reaches a terminal status (`APPROVED`, `REJECTED`, `EXPIRED`, or `CANCELED`).
* **Polling:** Call `GET /customers/{customerId}` and inspect `kycStatus`.
On `APPROVED`, the customer is ready to transact — proceed with account setup and unlock funding. On `REJECTED` or `EXPIRED`, surface the appropriate next step (for example, regenerate the link or request manual review).
## Step 2: Create an External Account for the Destination Wallet
Register the customer's Spark wallet as an external account so it can be used as a quote destination.
### Request
```bash theme={null}
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"
}
}'
```
### Response
```json theme={null}
{
"id": "ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456",
"customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
"status": "ACTIVE",
"currency": "BTC",
"accountInfo": {
"accountType": "SPARK_WALLET",
"address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu"
}
}
```
External accounts can be reused across multiple quotes. Register once, then reference by ID.
## Step 3: Create a Quote for Fiat-to-Crypto Conversion
Create a quote to convert USD to Bitcoin and deliver it to the Spark wallet. The quote will provide the current exchange rate and payment instructions for funding.
### Request
```bash theme={null}
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": {
"destinationType": "ACCOUNT",
"accountId": "ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456"
},
"lockedCurrencySide": "SENDING",
"lockedCurrencyAmount": 10000,
"description": "On-ramp: Buy $100 of Bitcoin"
}'
```
### Response
```json theme={null}
{
"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 4: 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.
In Sandbox, you can simulate funding using the `/sandbox/send` endpoint:
```bash theme={null}
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:**
```json theme={null}
{
"id": "Transaction:019542f5-b3e7-1d02-0000-000000000025",
"status": "PROCESSING",
"type": "OUTGOING",
"quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006"
}
```
In production, your customer or platform would initiate a bank transfer to the provided account details, include the reference code `RAMP-ABC123` in the transfer memo, and wait for Grid to detect the incoming payment (typically 1-3 business days for ACH, instant for RTP/wire). You'll receive a webhook notification when Bitcoin is delivered to the Spark wallet.
The reference code is critical for matching your payment to the quote. Always
include it exactly as provided in the payment instructions.
***
## Step 5: Receive Completion Webhook
Once Grid receives your payment and completes the USD-to-BTC conversion and delivery, you'll receive a webhook notification:
```json theme={null}
{
"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:
1. ✅ Created a customer via API
2. ✅ Registered the destination Spark wallet as an external account
3. ✅ Created a quote with exchange rate and payment instructions
4. ✅ Funded the quote using JIT payment (simulated in sandbox)
5. ✅ 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](/ramps/conversion-flows/fiat-crypto-conversion)
* **Self-custody wallets**: Explore advanced wallet integration in the [Self-Custody Wallets guide](/ramps/conversion-flows/self-custody-wallets)
* **Webhook verification**: Implement signature verification for security (see [Webhooks guide](/ramps/platform-tools/webhooks))
* **Sandbox testing**: Learn more about testing in the [Sandbox Testing guide](/ramps/platform-tools/sandbox-testing)
## Related Resources
* [API Reference](/api-reference) - Complete API documentation
* [Implementation Overview](/ramps/onboarding/implementation-overview) - High-level architecture and flow
* [Platform Configuration](/ramps/onboarding/platform-configuration) - Configure your platform settings