Get Lightning Invoices

Returns all previously created invoices.

Auth:Bearer <api_key>

Tags:LightningInvoices

Request

cURL

curl -G https://publicapi.sandbox.hercle.financial/api/v1/invoices \
  -H "Authorization: Bearer eyJhb..." \

Headers

Name	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication
Content-Type	string	Yes	application/json

Response

Success Response Schema

Successfully retrieved invoices

Field	Type	Description
`invoices`	array	List of Lightning invoices
`invoices[].id`	string	Unique identifier for the invoice
`invoices[].userId`	string	User ID associated with the invoice
`invoices[].email`	string	Email address associated with the invoice
`invoices[].encodedPaymentRequest`	string	Encoded Lightning payment request
`invoices[].expiresAt`	string	ISO 8601 timestamp when the invoice expires
`invoices[].status`	string	Invoice status
`invoices[].createdAt`	string \| null	ISO 8601 timestamp of invoice creation
`invoices[].updatedAt`	string \| null	ISO 8601 timestamp of last update
`invoices[].memo`	string	Memo or description for the invoice
`invoices[].paymentHash`	string	Payment hash
`invoices[].paymentPreimage`	string	Payment preimage
`invoices[].nodeId`	string	Lightning node ID
`invoices[].invoiceType`	string	Type of invoice
`invoices[].expirySecs`	number \| null	Invoice expiry time in seconds
`invoices[].metadata`	string	Additional invoice metadata
`invoices[].umaPostTransactionData`	string	UMA post-transaction data
`invoices[].bitcoinNetwork`	string	Bitcoin network (mainnet/testnet)
`invoices[].amountOriginalValue`	number \| null	Original invoice amount value
`invoices[].amountOriginalUnit`	string	Original invoice amount unit (e.g., BTC, satoshi)
`invoices[].amountPreferredCurrencyUnit`	string	Preferred currency unit (e.g., USD, EUR)
`invoices[].amountPreferredCurrencyValueRounded`	number \| null	Preferred currency value (rounded)
`invoices[].amountPreferredCurrencyValueApprox`	number \| null	Preferred currency value (approximate)
`invoices[].domainEvents`	array	Domain events associated with the invoice

Responses

Successfully retrieved invoices

200 application/json

{
  "invoices": [
    {
      "id": "inv_abc123def456",
      "userId": "user_789xyz",
      "email": "user@example.com",
      "encodedPaymentRequest": "lnbc10u1p3xnhl2pp5jmxtqn235tkjzf...",
      "expiresAt": "2024-03-28T17:03:12.456Z",
      "status": "OPEN",
      "createdAt": "2024-03-28T16:03:12.456Z",
      "updatedAt": null,
      "memo": "Payment for services",
      "paymentHash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
      "paymentPreimage": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
      "nodeId": "02a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
      "invoiceType": "STANDARD",
      "expirySecs": 3600,
      "metadata": "{}",
      "umaPostTransactionData": "",
      "bitcoinNetwork": "mainnet",
      "amountOriginalValue": 1000,
      "amountOriginalUnit": "satoshi",
      "amountPreferredCurrencyUnit": "USD",
      "amountPreferredCurrencyValueRounded": 1,
      "amountPreferredCurrencyValueApprox": 0.65,
      "domainEvents": []
    }
  ]
}

API Tester

Test this endpoint directly against the sandbox environment

API Key

Get your API key from Hercle Sandbox

Request URL

https://publicapi.sandbox.hercle.financial/api/v1/invoices