Lightning Address
Recibir sats en [email protected] desde cualquier wallet Lightning (LUD-16), activar y gestionar la dirección del usuario autenticado.
Cada usuario puede activar una Lightning Address con la forma [email protected]. Cualquier wallet Lightning del mundo (Phoenix, Wallet of Satoshi, Blink, Alby, Zeus, Breez…) puede pagarle a esa dirección y el pago se acredita al momento en el saldo de QvaPay en USD, al precio de BTC del momento, con la misma comisión que un depósito por Lightning (la vigente sale en fees.usd_pct de GET /user/lightning-address; las cuentas GOLD tienen la suya). Cuando la opción está disponible, el usuario puede elegir recibir en sats: entran sin conversión y sin comisión a su saldo de satoshis (satoshis).
La dirección implementa LUD-16 sobre LUD-06 (payRequest) y admite comentarios (LUD-12) de hasta 255 caracteres.
- Quién puede activarla: toda cuenta con la verificación de identidad (KYC) aprobada, sea personal o de empresa, también las de US persons. No hay excepciones por rol ni por tipo de cuenta.
- El nombre es fijo: por defecto es tu nombre de usuario en minúsculas y no cambia aunque cambies tu nombre de usuario. Si cambias el nombre de la dirección, la anterior deja de funcionar y queda reservada: nadie más puede usarla.
- Límites (se ajustan sin aviso): un mínimo y un máximo por pago y un máximo por usuario en 24 horas. Los valores vigentes salen en
limitsdeGET /user/lightning-address, y los montos que acepta la dirección enminSendable/maxSendablede la consulta LNURL.
GET /user/lightning-address
Estado de la Lightning Address del usuario y sus últimos cobros.
Autenticación
Bearer Token (Authorization: Bearer {token}).
Request
curl https://api.qvapay.com/user/lightning-address \
-H "Authorization: Bearer {token}"| Parámetro | Tipo | Descripción |
|---|---|---|
page | number | Página de payments (20 por página). Opcional. |
Response
{
"data": {
"visible": true,
"available": true,
"receiving": true,
"reason_code": null,
"message": null,
"address": {
"uuid": "0b9f3c1e-6a2d-4c5b-9e7f-2a1b3c4d5e6f",
"name": "erich",
"address": "[email protected]",
"lnurl": "LNURL1DP68GURN8GHJ7AMHWUH8ZANPWPSHJTNRDAKJ7TNHV4KXCTTTDEHHWM30D3H82UNVWQHK2UNFVD5QNY3K9Z",
"qr": "lightning:LNURL1DP68GURN8GHJ7AMHWUH8ZANPWPSHJTNRDAKJ7TNHV4KXCTTTDEHHWM30D3H82UNVWQHK2UNFVD5QNY3K9Z",
"status": "active",
"receive_as": "usd",
"created_at": "2026-10-30T12:00:00.000Z"
},
"domain": "qvpay.me",
"suggested_name": null,
"renames_left": 2,
"limits": { "min_usd": 0.1, "max_usd": 500, "daily_usd": 1000, "used_24h_usd": 14.61, "remaining_usd": 985.39 },
"receive": { "as": "usd", "effective": "usd", "sats_available": true },
"fees": { "usd_pct": 0.5, "sats_pct": 0 },
"satoshis": 1250,
"payments": [
{
"uuid": "6c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
"address": "[email protected]",
"sats": 21000,
"credit_usd": "14.54",
"credit_unit": "usd",
"comment": "Gracias por el café",
"paid_at": "2026-10-30T12:05:00.000Z",
"transaction_uuid": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d"
}
]
}
}Campos de respuesta
| Campo | Tipo | Descripción |
|---|---|---|
data.visible | boolean | La función está abierta para esta cuenta |
data.available | boolean | La cuenta cumple los requisitos para recibir |
data.receiving | boolean | Hay una dirección activa que está recibiendo pagos |
data.reason_code | string | null | Por qué no recibe: KYC, ROLE, DEPOSITS_DISABLED, PAUSED, BLOCKED, UNAVAILABLE, MODE_OFF, NOT_BETA… |
data.message | string | null | Explicación del motivo para mostrar al usuario |
data.address | object | null | La dirección vigente, o null si no la ha activado |
data.address.lnurl | string | La misma dirección como LNURL (LUD-01), en mayúsculas para el QR |
data.address.qr | string | Valor recomendado para el QR (lightning: + LNURL) |
data.address.status | string | active, paused o blocked |
data.address.receive_as | string | usd o sats: cómo eligió recibir el usuario |
data.domain | string | Dominio de las direcciones ({name}@{domain}), para mostrarlo junto al campo del nombre antes de activar |
data.suggested_name | string | null | Nombre propuesto para activar (tu nombre de usuario, si está libre) |
data.renames_left | number | Cambios de nombre que quedan |
data.limits | object | Límites vigentes en USD y lo usado en las últimas 24 h. En sats rigen los mismos, por su equivalente en USD |
data.receive.as | string | usd o sats: lo que eligió el usuario |
data.receive.effective | string | En qué se acreditará un pago nuevo. Es usd aunque el usuario haya elegido sats si la opción no está disponible |
data.receive.sats_available | boolean | Se puede elegir recibir en sats |
data.fees.usd_pct | number | Comisión (en %) de un cobro que entra en USD: la de depósito por Lightning, la de GOLD si la cuenta es GOLD |
data.fees.sats_pct | number | Comisión (en %) de un cobro que entra en sats: 0 |
data.satoshis | number | Saldo de satoshis del usuario |
data.payments | array | Cobros acreditados, más recientes primero. comment lo escribió quien pagó y no está verificado |
data.payments[].credit_usd | string | En USD, lo que se acreditó al saldo, ya descontada la comisión. En sats, el equivalente en USD de los sats recibidos |
data.payments[].credit_unit | string | usd (se acreditó credit_usd al saldo) o sats (se acreditaron sats al saldo de satoshis, sin comisión) |
POST /user/lightning-address
Activa, renombra, pausa o reanuda la dirección, o elige si los cobros entran en USD o en sats. Responde el mismo objeto que GET.
Autenticación
Bearer Token (Authorization: Bearer {token}). Requiere la verificación de identidad (KYC) aprobada.
Request
curl -X POST https://api.qvapay.com/user/lightning-address \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{ "action": "activate", "name": "erich" }'| Campo | Tipo | Descripción |
|---|---|---|
action | string | activate, rename, pause, resume o receive |
name | string | Nombre de la dirección. Opcional en activate (por defecto, tu nombre de usuario); obligatorio en rename. De 3 a 32 caracteres: letras minúsculas, números y . _ -, empezando y acabando en letra o número |
receive_as | string | Con action: "receive": usd o sats. Se aplica a los pagos nuevos; un pago en camino se acredita como estaba |
Errores
| Código HTTP | code | Significado |
|---|---|---|
| 400 | LN_NAME_INVALID | El nombre no cumple el formato (problem: length, format o reserved) |
| 403 | LN_ADDRESS_UNAVAILABLE | La cuenta no puede recibir (reason_code y message explican por qué) |
| 403 | KYC_REQUIRED | La cuenta no tiene la verificación de identidad aprobada |
| 409 | LN_NAME_TAKEN | El nombre no está disponible |
| 409 | LN_RENAME_LIMIT | Ya se usaron todos los cambios de nombre |
| 409 | LN_ADDRESS_EXISTS | Ya hay una dirección activada (usa rename) |
| 409 | LN_SATS_DISABLED | Recibir en sats no está disponible (volver a usd siempre se puede) |
| 429 | Demasiadas solicitudes |
Endpoints LNURL públicos
Los usa la wallet de quien paga; no llevan autenticación y responden con Access-Control-Allow-Origin: *.
GET https://qvpay.me/.well-known/lnurlp/{name}
Respuesta payRequest de LUD-06. Los montos van en millisatoshis y siempre son sats enteros (múltiplos de 1000).
{
"tag": "payRequest",
"callback": "https://www.qvapay.com/.well-known/lnurlp/erich/callback",
"minSendable": 143000,
"maxSendable": 714285000,
"metadata": "[[\"text/plain\",\"Pago a erich en QvaPay\"],[\"text/identifier\",\"[email protected]\"]]",
"commentAllowed": 255
}[email protected] funciona igual que [email protected] (el tag se ignora).
GET {callback}?amount={msat}&comment={texto}
Devuelve la factura Lightning por exactamente amount msat, con description_hash = sha256 de metadata. La factura vence a los pocos minutos y el precio queda fijado durante ese tiempo.
{
"pr": "lnbc210u1p...",
"routes": [],
"successAction": { "tag": "message", "message": "Pago enviado a [email protected]. ¡Gracias!" }
}Errores LNURL
Siguen LUD-06: { "status": "ERROR", "reason": "…" }.
| Código HTTP | Cuándo |
|---|---|
| 404 | La dirección no existe (o se renombró) |
| 200 | La dirección no puede recibir ahora, el monto está fuera de rango o no es un número entero de sats |
| 429 | Demasiadas solicitudes |
Notificación al recibir
Cuando un pago se acredita, el usuario recibe un email, un mensaje de Telegram (si lo tiene vinculado) y un push con data.type = "ln_address_received", data.transaction_uuid y data.unit (usd o sats). En el historial el cobro es una transacción con la descripción Lightning Address {name}@qvpay.me: {sats} sats. Si se acreditó en sats, la descripción acaba en (saldo en sats) y el importe de la transacción es el equivalente en USD: el saldo en USD no cambia.
Los sats recibidos se pueden usar como descuento en la tienda o retirar por Lightning con POST /withdraw usando source: "satoshis" y pay_method: "BTCLN".
Para enviarle dinero a otro usuario de QvaPay usa una transferencia: los retiros BTCLN a una Lightning Address de QvaPay (la dirección, su LNURL o una factura suya) se rechazan con 400 y code: "LN_SELF_PAY", en POST /withdraw y en POST /lightning/decode.
Recargar saldo (TopUp Cripto)
Generar una billetera cripto para recibir un depósito en tu cuenta de QvaPay. Funciona tanto para usuarios recargando su propio saldo como para apps/merchants que integren depósitos.
Identidad Nostr
Verificar la cuenta de Nostr del usuario como [email protected] (NIP-05), con el mismo nombre que su Lightning Address.