Skip to main content

API Reference

The Lightning Enable API is a RESTful web service for integrating Bitcoin Lightning payments into your platform.

Base URL​

https://api.lightningenable.com

Authentication​

All API requests require authentication via the X-API-Key header:

curl -X GET https://api.lightningenable.com/api/merchant/me \
  -H "X-API-Key: YOUR_API_KEY"

See Authentication for details.

API Endpoints​

Payments​

MethodEndpointDescription
POST/api/paymentsCreate payment invoice
GET/api/payments/{invoiceId}/statusPublic payment status (no API key — safe for browser polling)
GET/api/payments/{invoiceId}Get payment by ID
GET/api/payments/order/{orderId}Get payment by order ID
POST/api/payments/{invoiceId}/syncSync status from your payment provider

Refunds​

MethodEndpointDescription
POST/api/refundsCreate refund
GET/api/refunds/{refundId}Get refund status
GET/api/refundsList all refunds
GET/api/refunds/invoice/{invoiceId}Get refunds for invoice
POST/api/refunds/{refundId}/syncSync refund status from your payment provider

L402 Protocol​

MethodEndpointDescription
POST/api/l402/challengesCreate an L402 challenge (producer API)
POST/api/l402/challenges/verifyVerify an L402 token (producer API)
GET/api/l402/pricingGet L402 endpoint pricing
GET/api/l402/statusCheck L402 auth status
*/l402/proxy/{proxyId}/*L402-protected proxy

See the Producer API Reference for the challenge/verify contract.

Webhooks​

MethodEndpointDescription
POST/api/webhooks/opennodeOpenNode webhook receiver
POST/api/webhooks/strikeStrike webhook receiver

These receive events from your payment provider — your own notifications arrive at the callback URL you configure. See Webhooks.

Merchant Settings (Self-Service)​

MethodEndpointDescription
GET/api/merchant/meGet account info and onboarding status
GET/api/merchant/subscriptionGet subscription details
GET/api/merchant/l402-statusGet L402 feature status
GET/api/merchant/api-key-infoAPI key metadata (created/last-rotated)
GET/api/merchant/quickstartGet onboarding guide
POST/api/merchant/regenerate-keyRegenerate your API key
PUT/api/merchant/payment-providerSwitch payment provider (Strike/OpenNode)
PUT/api/merchant/strike-keyUpdate Strike API key
PUT/api/merchant/opennode-keyUpdate OpenNode API key
PUT/api/merchant/webhook-urlUpdate webhook URL
POST/api/merchant/validate-strikeValidate Strike API key
POST/api/merchant/validate-opennodeValidate OpenNode API key

Full request/response schemas: Merchant Settings.

Health Check​

MethodEndpointDescription
GET/healthStructured health check (public, no auth required)

Request Format​

Headers​

HeaderRequiredDescription
X-API-KeyYesYour merchant API key
Content-TypeYes (POST/PUT)application/json
X-Idempotency-KeyNoPrevents duplicate payments/refunds (UUID recommended)
X-Correlation-IdNoRequest tracing ID (auto-generated if not provided)

See Request Headers for full details on idempotency, correlation IDs, and API versioning.

Request Body​

POST and PUT requests accept JSON bodies:

{
  "orderId": "ORDER-12345",
  "amount": 99.99,
  "currency": "USD"
}

Response Format​

Success Response​

{
  "invoiceId": "1042",
  "status": "unpaid",
  "amount": 99.99,
  "currency": "USD"
}

Error Response​

Errors carry an error field (sometimes with a message); there is no machine-readable code field — dispatch on the HTTP status:

{ "error": "Invoice already exists for OrderId ORDER-12345" }

Model-binding validation failures return the standard ASP.NET validation problem shape (400 with an errors dictionary). See Errors.

HTTP Status Codes​

CodeDescription
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
402Payment Required - L402 payment needed
403Forbidden - Access denied
404Not Found - Resource doesn't exist
429Too Many Requests - Rate limited
500Server Error

Pagination​

List endpoints support pagination using skip and take parameters:

GET /api/refunds?skip=0&take=20
ParameterDefaultDescription
skip0Number of records to skip
take50Number of records to return (max 100)

Example - get second page of 20 results:

GET /api/refunds?skip=20&take=20

Rate Limiting​

PolicyLimitApplied To
Global100/minAll authenticated requests (per API key)
Read200/minGET operations
Payment Create10/minPOST /api/payments, POST /api/refunds
Admin30/minInternal admin endpoints

See Rate Limiting for details.

SDKs and Libraries​

Official L402 client libraries (auto-paying HTTP clients):

Official Agent SDKs (higher-level agent commerce primitives):

For MCP-server integration (Claude Desktop, Claude Code, etc.), see the Lightning Enable MCP repository.

Quick Examples​

Create Payment​

curl -X POST https://api.lightningenable.com/api/payments \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ORDER-12345",
    "amount": 49.99,
    "currency": "USD",
    "description": "Premium Subscription"
  }'

Check Payment Status​

curl https://api.lightningenable.com/api/payments/1042 \
  -H "X-API-Key: YOUR_API_KEY"

Create Refund​

curl -X POST https://api.lightningenable.com/api/refunds \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceId": "1042",
    "refundAddress": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "reason": "Customer request"
  }'

Health Check Endpoint​

The /health endpoint returns structured JSON describing the status of the API and its dependencies. It is public and does not require authentication, making it suitable for external monitoring and infrastructure health probes.

Request​

curl https://api.lightningenable.com/health

Response​

{
  "status": "Healthy",
  "totalDuration": 42.15,
  "checks": [
    {
      "name": "database",
      "status": "Healthy",
      "duration": 38.72,
      "description": null,
      "exception": null,
      "tags": ["db", "sql"]
    }
  ]
}

Response Fields​

FieldTypeDescription
statusstringOverall health: Healthy, Degraded, or Unhealthy
totalDurationnumberTotal time to run all checks (milliseconds)
checksarrayIndividual health check results
checks[].namestringName of the check (e.g., database)
checks[].statusstringCheck result: Healthy, Degraded, or Unhealthy
checks[].durationnumberTime for this check (milliseconds)
checks[].descriptionstring|nullOptional description from the check
checks[].exceptionstring|nullError message if the check failed
checks[].tagsarrayTags for categorizing checks (e.g., ["db", "sql"])

HTTP Status Codes​

CodeMeaning
200All checks passed (Healthy)
503One or more checks failed (Unhealthy)

Current Checks​

CheckTagsWhat It Verifies
databasedb, sqlSQL Server connectivity via EF Core CanConnectAsync

Unhealthy Response Example​

When the database is unreachable, the endpoint returns HTTP 503:

{
  "status": "Unhealthy",
  "totalDuration": 5023.41,
  "checks": [
    {
      "name": "database",
      "status": "Unhealthy",
      "duration": 5001.88,
      "description": null,
      "exception": "A network-related or instance-specific error occurred while establishing a connection to SQL Server.",
      "tags": ["db", "sql"]
    }
  ]
}

Using with Monitoring Tools​

Azure App Service Health Probes:

Configure in the Azure portal under Monitoring > Health check:

  • Path: /health
  • The probe will automatically mark the instance as unhealthy after consecutive failures.

UptimeRobot / Pingdom / External Monitors:

Point your uptime monitor at:

https://api.lightningenable.com/health
  • Alert on HTTP status code other than 200
  • Recommended check interval: 1 minute
  • Parse the JSON response to alert on specific check failures (e.g., checks[0].status != "Healthy")

curl Quick Check:

# Check overall status
curl -s https://api.lightningenable.com/health | jq '.status'

# Check database specifically
curl -s https://api.lightningenable.com/health | jq '.checks[] | select(.name == "database") | .status'

Next Steps​