> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lightspark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform Configuration

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

<Tip>
  Never share or expose your API secret. Rotate credentials periodically and
  restrict access to authorized systems only.
</Tip>

### Example: HTTP Basic Auth

```bash theme={null}
# 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_CLIENT_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`

<Note>
  The same base URL is used for both Sandbox and Production. Your API keys
  determine which environment processes your requests.
</Note>

## 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.

<Tip>
  Start with USD and BTC for the simplest on-ramp and off-ramp implementation,
  then add additional currencies as needed.
</Tip>

## 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

<Warning>
  For development, use reverse proxies like ngrok to expose local endpoints.
  Never use them in production.
</Warning>

### 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

<Info>
  The public key for verification is shown in the dashboard. Rotate keys when
  instructed by Lightspark support.
</Info>

### Test your webhook endpoint

Use the webhook test endpoint to verify your endpoint configuration:

```bash theme={null}
curl -sS -X POST 'https://api.lightspark.com/grid/2025-10-13/webhooks/test' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"
```

**Example test webhook payload:**

```json theme={null}
{
  "test": true,
  "timestamp": "2025-10-03T14:32:00Z",
  "webhookId": "Webhook:019542f5-b3e7-1d02-0000-000000000001",
  "type": "TEST"
}
```

<Check>
  If your endpoint receives the test webhook and responds with a 2xx status
  code, your webhook configuration is working correctly.
</Check>

## 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:

```bash theme={null}
curl -sS -X GET 'https://api.lightspark.com/grid/2025-10-13/config' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"
```

**Response example:**

```json theme={null}
{
  "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:

```bash theme={null}
curl -sS -X PATCH 'https://api.lightspark.com/grid/2025-10-13/config' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_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"]
      }
    ]
  }'
```

<Warning>
  Configuration changes take effect immediately. Test changes in Sandbox before
  applying to Production.
</Warning>