Referencia de API

Referencia de todos los endpoints REST de l402kit.com utilizados por ManagedProvider y la extensión de VS Code.

URL base: https://l402kit.com

Todas las respuestas son application/json. CORS está habilitado para todos los orígenes.

---

Facturas

Crear Factura

POST /api/invoice

Crea una factura Lightning BOLT11. Es llamado automáticamente por ManagedProvider — rara vez necesitas llamar esto directamente.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
amountSats	number	✅	Monto en satoshis (mín. 1)
ownerAddress	string	—	Tu Lightning Address. Requerido para que se ejecute la división.

Respuesta 200

{
  "paymentRequest": "lnbc10n1p...",
  "paymentHash":    "a1b2c3...",
  "macaroon":       "eyJoYXNoIjoiYTFiMm..."
}

Errores

Código	Motivo
400	amountSats faltante o inválido
429	Límite de solicitudes excedido (20 solicitudes/min por IP)
503	Proveedor Lightning temporalmente no disponible

---

Verificar Token

POST /api/verify

Valida un token L402 del lado del servidor sin el SDK.

Cuerpo de la solicitud

{ "token": "<macaroon>:<preimage>" }

Respuesta 200

{ "valid": true }

{ "valid": false, "error": "Token expired" }

---

División y Pagos

Ejecutar División

POST /api/split

Activa manualmente un pago de división 99.7/0.3% a una Lightning Address. Requiere el encabezado x-split-secret.

En la mayoría de los casos, la división se activa automáticamente a través del webhook de Blink. Utiliza este endpoint solo para recuperación manual o integraciones personalizadas.

Encabezados

Encabezado	Valor
x-split-secret	Tu variable de entorno SPLIT_SECRET

Cuerpo de la solicitud

{
  "amountSats":   1000,
  "ownerAddress": "[e-mail]"
}

Respuesta 200

{ "ok": true, "ownerSats": 997 }

Respuesta 200 (omitido — por debajo del mínimo)

{ "ok": true, "skipped": true }

---

Panel y Estadísticas

Obtener Estadísticas

GET /api/stats

Devuelve análisis de pagos. Requiere token de sesión LNURL-auth en el encabezado Authorization.

Respuesta 200

{
  "totalPayments": 42,
  "totalSats":     8400,
  "shinydappsFee": 25,
  "walletSats":    12345,
  "walletUsdCents": 456789,
  "byOwner": {
    "[e-mail]": { "count": 42, "sats": 8400 }
  },
  "byDay": {
    "2026-04-24": { "count": 5, "sats": 1000 }
  },
  "trend": {
    "payments7d": 12,
    "sats7d": 2400
  },
  "recent": [
    {
      "id": "uuid",
      "endpoint": "/api/data",
      "payment_hash": "a1b2...",
      "amount_sats": 100,
      "owner_address": "[e-mail]",
      "paid_at": "2026-04-24T10:00:00Z"
    }
  ]
}

---

Nivel Pro

Verificar Acceso Pro

GET /api/pro-check?address=[e-mail]

Devuelve si una Lightning Address tiene una suscripción Pro activa.

Respuesta 200

{ "active": true,  "expiresAt": "2026-05-24T10:00:00Z" }
{ "active": false }

Suscribirse a Pro

GET /api/dev-token?address=[e-mail]

Devuelve una factura Lightning para adquirir una suscripción Pro de 30 días (~9,000 sats).

Respuesta 200

{
  "priceSats": 9000,
  "invoice":   "lnbc90n1p...",
  "macaroon":  "eyJoYXNoIjoiY..."
}

POST /api/dev-token

Activa Pro después de pagar la factura.

Cuerpo de la solicitud

{ "macaroon": "...", "preimage": "..." }

Respuesta 200

{ "access": true, "expiresAt": "2026-05-24T10:00:00Z" }

---

Autenticación (LNURL-auth)

Iniciar Sesión

GET /api/lnurl-auth

Devuelve un desafío LNURL-auth para el inicio de sesión en el panel. Escanea el código QR en el panel.

Endpoint LNURL-pay

GET /.well-known/lnurlp/:username

Metadatos LNURL-pay estándar para la resolución de Lightning Address. Utilizado internamente por el mecanismo de división.

---

Demo

Índice de Demo

GET /api/demo

Devuelve información sobre los endpoints de demo disponibles.

Precio de BTC (de pago)

GET /api/demo/btc-price

Devuelve el precio en vivo de BTC. Requiere un token L402 válido (1 sat).

Devuelve 402 con factura + macaroon en la primera llamada. Reintenta con Authorization: L402 <macaroon>:<preimage>.

Revelar Preimage

GET /api/demo/preimage?hash=<paymentHash>

Después de pagar la factura de demo, llama a este endpoint con el paymentHash para recuperar tu preimage y construir el token L402.

---

Webhooks

Receptor de Webhook de Blink

POST /api/blink-webhook

Endpoint interno. Recibe confirmaciones de pago firmadas de Blink (Svix HMAC-SHA256). Activa la división y registra el pago. No está destinado para uso directo.

---

Directorio de APIs

Registrar una API

POST /api/register

Registra tu API protegida con L402 en el directorio público. Es llamado automáticamente por ManagedProvider.fromAddress() cuando se proporciona registerDirectory. Idempotente — seguro de llamar en cada inicio del servidor.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
url	string	✅	URL pública de tu endpoint L402
name	string	✅	Nombre para mostrar
price_sats	number	✅	Precio por llamada en satoshis (mín. 1)
lightning_address	string	✅	Tu Lightning Address
description	string	—	Descripción breve
category	string	—	data, ai, finance, weather, compute, storage u other

Respuesta 200

{ "ok": true, "id": "uuid" }

---

Listar APIs

GET /api/apis.json

Devuelve todas las APIs registradas. Legible por máquinas — diseñado para que los agentes descubran APIs de pago.

Parámetros de consulta

Parámetro	Descripción
category	Filtrar por categoría (data, ai, finance, weather, compute, storage, other)

Respuesta 200

{
  "version": "1",
  "count": 3,
  "apis": [
    {
      "url": "https://api.example.com/weather",
      "name": "Weather API",
      "description": "Live weather data, 1 sat per query",
      "price_sats": 1,
      "category": "weather",
      "created_at": "2026-04-26T10:00:00Z"
    }
  ]
}

---

Privacidad de Datos

Eliminar Mis Datos

POST /api/delete-data

Inicia un desafío LNURL-auth. Tras la verificación con la billetera, todos los registros de pago asociados con la clave pública autenticada se eliminan de forma permanente (derecho de supresión del RGPD).