createLightningInvoice

curl --request POST \
  --url https://api.privy.io/v1/wallets/{wallet_id}/rpc \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'privy-app-id: <privy-app-id>' \
  --data '{
  "method": "createLightningInvoice",
  "network": "MAINNET",
  "params": {
    "amount_sats": 20
  }
}'

{
  "method": "createLightningInvoice",
  "data": {
    "id": "SparkLightningReceiveRequest:019842c4-c50f-cd96-0000-612d71a61547",
    "created_at": "2025-07-25T18:07:28.527107+00:00",
    "updated_at": "2025-07-25T18:07:28.527107+00:00",
    "network": "MAINNET",
    "invoice": {
      "encodedInvoice": "lnbc...",
      "bitcoinNetwork": "MAINNET",
      "paymentHash": "f59c86aaafa9920f410d1567d9ee38bf526c932691c23c7bac6d8519682a6d76",
      "amount": {
        "originalValue": 20000,
        "originalUnit": "MILLISATOSHI",
        "preferredCurrencyUnit": "USD",
        "preferredCurrencyValueRounded": 2,
        "preferredCurrencyValueApprox": 2.3228803716608595
      },
      "createdAt": "2025-07-25T18:07:28.484042+00:00",
      "expiresAt": "2025-08-24T18:07:28.484042+00:00",
      "memo": null
    },
    "status": "INVOICE_CREATED",
    "typename": "LightningReceiveRequest",
    "payment_preimage": null,
    "receiver_identity_public_key": null
  }
}

POST

wallets

{wallet_id}

rpc

curl --request POST \
  --url https://api.privy.io/v1/wallets/{wallet_id}/rpc \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'privy-app-id: <privy-app-id>' \
  --data '{
  "method": "createLightningInvoice",
  "network": "MAINNET",
  "params": {
    "amount_sats": 20
  }
}'

{
  "method": "createLightningInvoice",
  "data": {
    "id": "SparkLightningReceiveRequest:019842c4-c50f-cd96-0000-612d71a61547",
    "created_at": "2025-07-25T18:07:28.527107+00:00",
    "updated_at": "2025-07-25T18:07:28.527107+00:00",
    "network": "MAINNET",
    "invoice": {
      "encodedInvoice": "lnbc...",
      "bitcoinNetwork": "MAINNET",
      "paymentHash": "f59c86aaafa9920f410d1567d9ee38bf526c932691c23c7bac6d8519682a6d76",
      "amount": {
        "originalValue": 20000,
        "originalUnit": "MILLISATOSHI",
        "preferredCurrencyUnit": "USD",
        "preferredCurrencyValueRounded": 2,
        "preferredCurrencyValueApprox": 2.3228803716608595
      },
      "createdAt": "2025-07-25T18:07:28.484042+00:00",
      "expiresAt": "2025-08-24T18:07:28.484042+00:00",
      "memo": null
    },
    "status": "INVOICE_CREATED",
    "typename": "LightningReceiveRequest",
    "payment_preimage": null,
    "receiver_identity_public_key": null
  }
}

Idempotency on errors: On 4xx or 5xx, Privy caches the response and replays it for the same key. Generate a new key to retry after a server error. Policy violations are an exception and allow same-key retries.

curl --request POST \
  --url https://api.privy.io/v1/wallets/{wallet_id}/rpc \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'privy-app-id: <privy-app-id>' \
  --data '{
  "method": "createLightningInvoice",
  "network": "MAINNET",
  "params": {
    "amount_sats": 20
  }
}'

{
  "method": "createLightningInvoice",
  "data": {
    "id": "SparkLightningReceiveRequest:019842c4-c50f-cd96-0000-612d71a61547",
    "created_at": "2025-07-25T18:07:28.527107+00:00",
    "updated_at": "2025-07-25T18:07:28.527107+00:00",
    "network": "MAINNET",
    "invoice": {
      "encodedInvoice": "lnbc...",
      "bitcoinNetwork": "MAINNET",
      "paymentHash": "f59c86aaafa9920f410d1567d9ee38bf526c932691c23c7bac6d8519682a6d76",
      "amount": {
        "originalValue": 20000,
        "originalUnit": "MILLISATOSHI",
        "preferredCurrencyUnit": "USD",
        "preferredCurrencyValueRounded": 2,
        "preferredCurrencyValueApprox": 2.3228803716608595
      },
      "createdAt": "2025-07-25T18:07:28.484042+00:00",
      "expiresAt": "2025-08-24T18:07:28.484042+00:00",
      "memo": null
    },
    "status": "INVOICE_CREATED",
    "typename": "LightningReceiveRequest",
    "payment_preimage": null,
    "receiver_identity_public_key": null
  }
}

Headers

string

required

ID of your Privy app.

string

Request authorization signature. If multiple signatures are required, they should be comma separated.

string

Request expiry. Value is a Unix timestamp in milliseconds representing the deadline by which the request must be processed.

Path Parameters

string

required

ID of the wallet to get.

These wallet methods are modeled after the Spark Wallet SDK. For more information about this wallet method, check out the Spark Wallet documentation.

Body

string

required

Available options: createLightningInvoice

string

required

Available options: MAINNET, REGTEST

object

required

Parameters for the invoice to be created.

Hide child attributes

number

required

The amount of sats to be received.

Returns

enum<string>

required

Always "createLightningInvoice"

object

required

Details about the created Lightning invoice.

Hide child attributes

string

required

Unique ID of the Lightning receive request.

string

required

Timestamp of invoice creation.

string

required

Timestamp of last update.

string

required

The Bitcoin network this invoice is valid for.

object

required

Encoded invoice details.

Hide child attributes

string

required

Bolt11-encoded Lightning invoice string.

string

required

The Bitcoin network.

string

required

The hash of the preimage for this payment request.

object

required

Amount details.

Hide child attributes

number

required

string

required

string

required

number

required

number

required

string

required

Timestamp of invoice creation.

string

required

Timestamp of invoice expiration.

string

Optional memo included with the invoice.

string

required

Current status of the invoice. Possible value: "INVOICE_CREATED".

string

required

string

Public key of the receiving node.

⌘I

API reference

Wallets

Wallet actions

Accounts

Policies

Condition sets

Aggregations

Transactions

Key quorums

Intents

Users

Labs

createLightningInvoice

Headers

Path Parameters

Body

Returns

​Headers

​Path Parameters

​Body

​Returns

Headers

Path Parameters

Body

Returns