Gyvar docs

Create an invoice

Mints a FRESH invoice every time. There is no get-or-create and there cannot be one: `/addresses` is idempotent on a reference you supply, but an invoice is amount-fixed and single-use, so the same trick does not apply. **A request that times out and is retried mints a SECOND invoice.** That is cheap rather than dangerous - an unpaid invoice expires on its own, and only one can ever be paid, because the credit is keyed on the payment hash. The cost is showing the wrong one to a payer, so prefer one mint per payment attempt over blind retries.

POST
/lightning/invoices

Authorization

KeyID Timestamp Nonce Signature
X-Gyvar-Key<token>

Your key id, gyv_k_live_... or gyv_k_sandbox_....

In: header

X-Gyvar-Timestamp<token>

Unix seconds. Must be within 5 minutes of our clock.

In: header

X-Gyvar-Nonce<token>

A unique value per request. Replays are rejected.

In: header

X-Gyvar-Signature<token>

Ed25519 signature over the canonical string. See the Signing guide.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

amount_sat*integer

Fixed into the invoice. Sats, not BTC - Lightning is denominated in them, and a decimal here would be a rounding argument on every request.

Range1 <= value

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/lightning/invoices" \  -H "Content-Type: application/json" \  -d '{    "amount_sat": 25000  }'
{  "data": {    "invoice": "string",    "amount_sat": 0,    "expires_at": "2019-08-24T14:15:22Z"  }}