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 an external account for the destination Spark wallet
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. Unregulated platforms can onboard customers either through the hosted KYC/KYB link flow or by submitting customer data directly through the API — for INDIVIDUAL customers (KYC), personal information goes through POST /customers; for BUSINESS customers (KYB), you also register beneficial owners via POST /beneficial-owners.

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

{
  "platformCustomerId": "b87d2e4a9c13f5b",
  "customerType": "BUSINESS",
  "businessInfo": {
    "legalName": "Acme Corporation",
    "registrationNumber": "789012345",
    "taxId": "123-45-6789",
    "incorporatedOn": "2018-03-14"
  },
  "address": {
    "line1": "456 Oak Avenue",
    "line2": "Floor 12",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US"
  }
}

Unregulated platforms rely on Grid to run KYC for individuals and KYB for businesses. You can onboard customers either through the hosted KYC/KYB link flow below, or by submitting customer data directly through the API. Both paths produce the same kycStatus transitions and emit the same CUSTOMER.KYC_APPROVED / CUSTOMER.KYC_REJECTED / CUSTOMER.KYC_PENDING (and CUSTOMER.KYB_* equivalents) webhooks.

Either path works for unregulated platforms:

Hosted flow: Redirect customers to a Grid-hosted link (or embed the provider SDK) for identity verification. Best when you want Grid to handle the entire collection UX.
Direct API onboarding: Collect customer information in your own UI and submit it via the API. For INDIVIDUAL customers (KYC), personal information goes through POST /customers. For BUSINESS customers (KYB), you also register beneficial owners via POST /beneficial-owners. Submit for review with POST /verifications.

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 for the full list of optional pre-fill fields.

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

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:

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

Create the customer

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.

Verify contact channels (only where required)

Some regions (for example, the EU) require the customer’s email and/or phone to be verified before KYC can begin. When this applies, the customer carries a contactVerification object listing only the channels that are required — for example { "email": "PENDING", "phone": "PENDING" }, or just { "email": "PENDING" } if a provider requires email alone. When the object is absent, no contact verification is required and you can skip this step.For each channel that’s present, drive a send-then-confirm pair (the provider delivers a one-time code by email/SMS):

POST /customers/{customerId}/verify-email, then POST /customers/{customerId}/verify-email/confirm with { "code": "..." }
POST /customers/{customerId}/verify-phone, then POST /customers/{customerId}/verify-phone/confirm with { "code": "..." }

Re-POST the send endpoint to resend a code. Each channel moves PENDING → VERIFIED. (verify-email/verify-phone return 409 for a channel the provider doesn’t require.)

Generating the KYC link before every present channel is VERIFIED returns 409.

Generate the KYC link

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.

Send the customer through 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.

Track the decision

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 CUSTOMER.KYC_APPROVED / CUSTOMER.KYC_REJECTED (and CUSTOMER.KYB_APPROVED / CUSTOMER.KYB_REJECTED for business customers) to be notified when the customer reaches a terminal status. CUSTOMER.KYC_PENDING (and the KYB_PENDING sibling) also fires when the customer is submitted for review — subscribe to it as well if you want to surface an “under review” state to the customer.
Polling: Call GET /customers/{customerId} and inspect kycStatus.

Handle completion

On APPROVED, the customer is ready to transact — proceed with account setup and unlock funding. On REJECTED, surface the appropriate next step (for example, regenerate the link or request manual review).

Direct API Onboarding

Prefer to collect identity information in your own UI and submit it to Grid yourself? Use the API directly instead of redirecting to a hosted link. The customer’s kycStatus transitions the same way and you receive the same CUSTOMER.KYC_APPROVED / CUSTOMER.KYC_REJECTED / CUSTOMER.KYC_PENDING (and CUSTOMER.KYB_* equivalents) webhooks.The shape of the flow depends on the customer type:

KYC (INDIVIDUAL customers) — supply the customer’s personal information through the customer endpoint. No beneficial owners are involved.
KYB (BUSINESS customers) — create the business customer, then register its beneficial owners, directors, and officers individually.

KYC (individual)
KYB (business)

Create the customer with personal information

Call POST /customers with customerType: INDIVIDUAL and the personal information collected from the customer (legal name, date of birth, address, nationality, etc.). The returned id is the customer’s Grid ID; kycStatus starts at PENDING.

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",
    "fullName": "Jane Doe",
    "birthDate": "1985-06-15",
    "nationality": "US",
    "email": "jane.doe@example.com",
    "address": {
      "line1": "123 Pine Street",
      "city": "Seattle",
      "state": "WA",
      "postalCode": "98101",
      "country": "US"
    }
  }'

Where the customer’s provider requires it (for example, EU customers), the customer carries a contactVerification object and their email and phone must be VERIFIED before you submit for verification. Drive each channel with the send-then-confirm pairs (verify-email / verify-email/confirm and verify-phone / verify-phone/confirm) described in the Hosted flow’s “Verify email and phone” step. When contactVerification is absent, no contact verification is required.

Upload supporting documents (if requested)

Some jurisdictions or currencies require an ID document or proof of address. Upload them with POST /documents using multipart/form-data, referencing the customer by customerId.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/documents" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -F "documentHolder=Customer:019542f5-b3e7-1d02-0000-000000000001" \
  -F "documentType=PASSPORT" \
  -F "documentNumber=A12345678" \
  -F "issuingAuthority=U.S. Department of State" \
  -F "country=US" \
  -F "file=@./passport.jpg"

Submit for verification

Call POST /verifications to submit the customer for review. The response includes a verificationStatus. If anything is missing, verificationStatus is RESOLVE_ERRORS and the errors array describes exactly what to collect before retrying.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/verifications" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  }'

Submitted successfully:

{
  "id": "Verification:019542f5-b3e7-1d02-0000-000000000002",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "verificationStatus": "IN_PROGRESS",
  "errors": [],
  "createdAt": "2025-10-03T12:00:00Z"
}

Blocked by missing data:

{
  "id": "Verification:019542f5-b3e7-1d02-0000-000000000001",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "verificationStatus": "RESOLVE_ERRORS",
  "errors": [
    {
      "resourceId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "type": "MISSING_PROOF_OF_ADDRESS_DOCUMENT",
      "acceptedDocumentTypes": ["PROOF_OF_ADDRESS"],
      "reason": "Proof of address document is required"
    }
  ],
  "createdAt": "2025-10-03T12:00:00Z"
}

Track the decision

Track terminal kycStatus transitions via the CUSTOMER.KYC_APPROVED / CUSTOMER.KYC_REJECTED webhook (recommended) or by polling GET /customers/{customerId}. CUSTOMER.KYC_PENDING also fires when the customer is submitted for review — subscribe to it if you want to surface an “under review” state. On APPROVED, unlock funding and money movement.

When Grid runs KYB for a business customer, the following information and documents are collected before onboarding completes. Use this list to plan what to gather from the business — provide it via POST /customers, POST /beneficial-owners, and POST /documents (or through the hosted flow).

Business identifying information

Entity full legal name
Doing Business As (DBA) name, if applicable
Physical address — the principal place of business, local office, or other physical location of the entity opening the account
Countries of operation
Identification number — U.S. taxpayer identification number, or, for a foreign business without one, alternative government-issued documentation certifying the existence of the business

Ownership and control structure

Collected for:

One control person — a single individual with significant responsibility to control, manage, or direct the legal entity, and
All beneficial owners — every individual who owns 25% or more of the legal entity, directly or indirectly.

For every such individual, provide:

Full name
Date of birth
Address
Identification number, by residency:
- U.S. persons — Social Security Number (SSN) or Individual Taxpayer Identification Number (ITIN)
- Non-U.S. persons — one or more of: ITIN, passport number with country of issuance, alien identification card number, or another government-issued document evidencing nationality or residence and bearing a photograph or similar safeguard

Required documents

Company formation and existence documents. For example:
- Certificate of incorporation
- Articles of association
Proof of ownership and control structure. For example:
- Corporate organization and ownership chart
- Shareholder agreements
- Operating agreements
- Register of members
- Certification of controlling person and beneficial owners
Proof of address, dated within the last 3 months. For example:
- Utility bill
- Bank statement
- Lease agreement
- Official correspondence
Tax ID or equivalent identifying-number documents
For non-U.S. beneficial owners — passport plus one additional government-issued ID. For example:
- National ID

Create the business customer

Call POST /customers with customerType: BUSINESS and the business information (legal name, registration number, tax ID, registered address).

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": "BUSINESS",
    "platformCustomerId": "b87d2e4a9c13f5b",
    "businessInfo": {
      "legalName": "Acme Corporation",
      "registrationNumber": "789012345",
      "taxId": "123-45-6789",
      "incorporatedOn": "2018-03-14"
    },
    "address": {
      "line1": "456 Oak Avenue",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  }'

Register each beneficial owner, director, or officer with POST /beneficial-owners. Each one is verified individually with their own personal information.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/beneficial-owners" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "roles": ["DIRECTOR"],
    "ownershipPercentage": 40,
    "personalInfo": {
      "firstName": "Jane",
      "lastName": "Doe",
      "birthDate": "1985-06-15",
      "nationality": "US",
      "address": {
        "line1": "123 Pine Street",
        "city": "Seattle",
        "state": "WA",
        "postalCode": "98101",
        "country": "US"
      },
      "idType": "SSN",
      "identifier": "123-45-6789"
    }
  }'

Upload supporting documents

Upload business documents (registration, articles of incorporation) and any documents required for individual beneficial owners with POST /documents. Reference the company by customerId and each owner by beneficialOwnerId.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/documents" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -F "documentHolder=BeneficialOwner:019542f5-b3e7-1d02-0000-00000000abcd" \
  -F "documentType=PASSPORT" \
  -F "documentNumber=B98765432" \
  -F "issuingAuthority=U.S. Department of State" \
  -F "country=US" \
  -F "file=@./owner-passport.jpg"

Submit for verification

Call POST /verifications to submit the business for review. The response includes a verificationStatus. If beneficial owners, fields, or documents are missing, verificationStatus is RESOLVE_ERRORS and the errors array tells you exactly what to collect — note that resourceId may point at either the customer or a specific beneficial owner.

curl -X POST "https://api.lightspark.com/grid/2025-10-13/verifications" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  }'

Blocked by missing data:

{
  "id": "Verification:019542f5-b3e7-1d02-0000-000000000001",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "verificationStatus": "RESOLVE_ERRORS",
  "errors": [
    {
      "resourceId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "type": "MISSING_FIELD",
      "field": "customer.address.line1",
      "reason": "Business address line 1 is required"
    },
    {
      "resourceId": "BeneficialOwner:019542f5-b3e7-1d02-0000-000000000002",
      "type": "MISSING_FIELD",
      "field": "personalInfo.birthDate",
      "reason": "Date of birth is required for beneficial owners"
    }
  ],
  "createdAt": "2025-10-03T12:00:00Z"
}

Submitted successfully:

{
  "id": "Verification:019542f5-b3e7-1d02-0000-000000000002",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "verificationStatus": "IN_PROGRESS",
  "errors": [],
  "createdAt": "2025-10-03T12:00:00Z"
}

Track the decision

Track terminal kycStatus transitions via the CUSTOMER.KYB_APPROVED / CUSTOMER.KYB_REJECTED webhook (recommended) or by polling GET /customers/{customerId}. CUSTOMER.KYB_PENDING also fires when the business is submitted for review — subscribe to it if you want to surface an “under review” state. On APPROVED, unlock funding and money movement.

Step 2: Create an External Account for the Destination Wallet

Request

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

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

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": "REALTIME_FUNDING",
      "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

{
  "id": "Quote:019542f5-b3e7-1d02-0000-000000000006",
  "status": "PENDING",
  "createdAt": "2025-10-03T15:00:00Z",
  "expiresAt": "2025-10-03T15: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": 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.

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" \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "Quote:019542f5-b3e7-1d02-0000-000000000006",
    "currencyCode": "USD"
  }'

Response:

{
  "id": "Transaction:019542f5-b3e7-1d02-0000-000000000025",
  "status": "PROCESSING",
  "type": "OUTGOING",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "platformCustomerId": "customer_12345",
  "source": {
    "sourceType": "REALTIME_FUNDING",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  },
  "destination": {
    "destinationType": "ACCOUNT",
    "accountId": "ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456"
  },
  "sentAmount": { "amount": 10000, "currency": { "code": "USD", "decimals": 2 } },
  "receivedAmount": { "amount": 83333, "currency": { "code": "BTC", "decimals": 8 } },
  "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:

{
  "id": "Webhook:019542f5-b3e7-1d02-0000-000000000030",
  "type": "OUTGOING_PAYMENT.COMPLETED",
  "timestamp": "2025-10-03T15:03:00Z",
  "data": {
    "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",
          "reference": "REF123456"
        }
      }
    ]
  }
}

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
✅ Registered the destination Spark wallet as an external account
✅ 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

Overview

Onboarding

Managing accounts

Conversion flows

Global Accounts

Platform tools

Prerequisites

Overview

Step 1: Customer Onboarding

Creating Customers via Direct API

Hosted KYC Link Flow

1. Create the customer

2. Generate a KYC link

Complete KYC Process

Direct API Onboarding

Business identifying information

Ownership and control structure

Required documents

Step 2: Create an External Account for the Destination Wallet

Request

Response

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

Request

Response

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

Step 5: Receive Completion Webhook

Summary

Next Steps

​Prerequisites

​Overview

​Step 1: Customer Onboarding

​Creating Customers via Direct API

​Hosted KYC Link Flow

​1. Create the customer

​2. Generate a KYC link

​Complete KYC Process

​Direct API Onboarding

​Business identifying information

​Ownership and control structure

​Required documents

​Step 2: Create an External Account for the Destination Wallet

​Request

​Response

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

​Request

​Response

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

​Step 5: Receive Completion Webhook

​Summary

​Next Steps

​Related Resources

Prerequisites

Overview

Step 1: Customer Onboarding

Creating Customers via Direct API

Hosted KYC Link Flow

1. Create the customer

2. Generate a KYC link

Complete KYC Process

Direct API Onboarding

Business identifying information

Ownership and control structure

Required documents

Step 2: Create an External Account for the Destination Wallet

Request

Response

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

Request

Response

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

Step 5: Receive Completion Webhook

Summary

Next Steps

Related Resources