Skip to main content
This guide explains how to configure your platform for ramp operations: get API credentials, configure webhooks, and set up supported currencies for conversions.

​
API credentials and authentication

Create API credentials in the Grid dashboard. Credentials are scoped to an environment (Sandbox or Production) and cannot be used across environments.
  • Authentication: Use HTTP Basic Auth with your API key and secret in the Authorization header
  • Environment isolation: Sandbox keys only work against Sandbox; Production keys only work against Production
Never share or expose your API secret. Rotate credentials periodically and restrict access to authorized systems only.

​
Example: HTTP Basic Auth

# Using cURL's Basic Auth shorthand (-u):
curl -sS -X GET 'https://api.lightspark.com/grid/2025-10-13/config' \
  -u "$GRID_CLIENT_ID:$GRID_API_SECRET"

​
Base API path

The base API path is consistent across environments; your credentials determine which environment you’re accessing. Base URL: https://api.lightspark.com/grid/2025-10-13
The same base URL is used for both Sandbox and Production. Your API keys determine which environment processes your requests.

​
Supported currencies

During onboarding, configure the currencies your platform will support for conversions. Grid supports:

​
Fiat Currencies

  • USD (United States Dollar) - Primary fiat currency
  • EUR (Euro)
  • GBP (British Pound)
  • MXN (Mexican Peso)
  • And more regional currencies

​
Cryptocurrencies

  • Bitcoin (BTC) via Spark, L1, or Lightning Network
  • Stablecoins
You can add or remove supported currencies anytime in the Grid dashboard. For pre-funded models, Grid automatically creates internal accounts for each supported currency.
Start with USD and BTC for the simplest on-ramp and off-ramp implementation, then add additional currencies as needed.

​
Webhooks and notifications

Configure your webhook endpoint to receive real-time notifications about conversion status, transaction completion, and account balance updates.

​
Webhook setup

  1. Create a public HTTPS endpoint to receive webhook notifications
  2. Configure the endpoint URL in the Grid dashboard
  3. Verify webhook signatures using the Grid public key (provided in dashboard)
  4. Respond with 2xx status codes to acknowledge receipt
  5. Process events idempotently to handle duplicate deliveries
For development, use reverse proxies like ngrok to expose local endpoints. Never use them in production.

​
Webhook signature verification

Webhooks use asymmetric (public/private key) signatures for security:
  • Verify the X-Grid-Signature header against the exact request body
  • Use the Grid public key from your dashboard
  • Reject webhooks with invalid signatures
The public key for verification is shown in the dashboard. Rotate keys when instructed by Lightspark support.

​
Test your webhook endpoint

Use the webhook test endpoint to verify your endpoint configuration: 
curl -sS -X POST 'https://api.lightspark.com/grid/2025-10-13/webhooks/test' \
  -u "$GRID_CLIENT_ID:$GRID_API_SECRET"
Example test webhook payload: 
{
  "test": true,
  "timestamp": "2025-10-03T14:32:00Z",
  "webhookId": "Webhook:019542f5-b3e7-1d02-0000-000000000001",
  "type": "TEST"
}
If your endpoint receives the test webhook and responds with a 2xx status code, your webhook configuration is working correctly.

​
Conversion limits

Configure minimum and maximum amounts for conversions per currency:
  • Minimum amounts: Prevent uneconomical micro-conversions
  • Maximum amounts: Manage risk and liquidity requirements
  • Per-transaction limits: Configurable in the dashboard

​
Retrieve platform configuration

You can retrieve your current platform configuration programmatically: 
curl -sS -X GET 'https://api.lightspark.com/grid/2025-10-13/config' \
  -u "$GRID_CLIENT_ID:$GRID_API_SECRET"
Response example: 
{
  "id": "PlatformConfig:019542f5-b3e7-1d02-0000-000000000003",
  "webhookEndpoint": "https://api.example.com/webhooks/grid",
  "supportedCurrencies": [
    {
      "currencyCode": "USD",
      "minAmount": 100,
      "maxAmount": 1000000,
      "enabledTransactionTypes": ["OUTGOING", "INCOMING"]
    },
    {
      "currencyCode": "BTC",
      "minAmount": 1000,
      "maxAmount": 10000000,
      "enabledTransactionTypes": ["OUTGOING", "INCOMING"]
    }
  ],
  "createdAt": "2025-09-01T12:30:45Z",
  "updatedAt": "2025-10-01T10:00:00Z"
}

​
Update platform configuration

Update your platform configuration using the PATCH endpoint: 
curl -sS -X PATCH 'https://api.lightspark.com/grid/2025-10-13/config' \
  -u "$GRID_CLIENT_ID:$GRID_API_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "webhookEndpoint": "https://api.mycompany.com/webhooks/grid",
    "supportedCurrencies": [
      {
        "currencyCode": "USD",
        "minAmount": 100,
        "maxAmount": 1000000,
        "enabledTransactionTypes": ["OUTGOING", "INCOMING"]
      },
      {
        "currencyCode": "BTC",
        "minAmount": 1000,
        "maxAmount": 10000000,
        "enabledTransactionTypes": ["OUTGOING", "INCOMING"]
      }
    ]
  }'
Configuration changes take effect immediately. Test changes in Sandbox before applying to Production.
⌘I