Authentication

Every API request includes your API key in the x-api-key header.

x-api-key: <api_key>

API keys are backend credentials. Keep them in server-side configuration, secret storage, or your deployment platform’s encrypted environment variables.

Never expose API keys in browser JavaScript, mobile apps, public repositories, screenshots, analytics events, or client-side error logs.

Test keys

You can request a separate test API key with the lsk_test_ prefix from support. Test keys run against the live API with real liquidity, so every test swap is a real transaction. Use small amounts. There is no sandbox environment.

Rate limits

Each API key allows 120 requests per minute. Exceeding it returns 429 with the rate_limited code. When a retry delay is available, the response includes a Retry-After header:

Retry-After: 30

Wait at least that many seconds before retrying. Polling a swap every 30 seconds uses a tiny fraction of the limit; the limit exists to catch broken retry loops, not normal usage.

Authentication errors

Errors use the shared error shape:

{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is invalid.",
    "details": {}
  },
  "requestId": "req_123"
}

Code	Meaning
`invalid_api_key`	The key is missing or invalid.
`inactive_partner`	API access is disabled for this account.

The full error list, including rate_limited, is on Statuses and errors.

Order attribution

POST /quote accepts two optional fields that connect a LightSwap swap to your own records:

externalId: your order reference. Set it at quote creation and keep it through support conversations.
customerId: your user reference, carried on the swap payload.

{
  "customerId": "u_123",
  "externalId": "order-123",
  "from": {
    "network": "bitcoin",
    "token": "BTC",
    "amount": "0.01"
  },
  "to": {
    "network": "tron",
    "token": "USDT"
  }
}

Recommended practice:

Always set externalId on quote creation.
Store the resulting swap ID next to it. The swap ID is the unique reference; LightSwap doesn’t enforce externalId uniqueness, so treat it as a label, not a key.
Quote the externalId first when you contact support about an order.

Get started

Direct API

Widget

API Reference

Test keys

Rate limits

Authentication errors

Order attribution

​Test keys

​Rate limits

​Authentication errors

​Order attribution

Test keys

Rate limits

Authentication errors

Order attribution