Lexe Python SDK ¶

get_human_bitcoin_address()¶

Get the user’s Human Bitcoin Address.

The Human Bitcoin Address (BIP 353), e.g. ₿username@lexe.app, is a human-readable address which others can pay to send Bitcoin to this wallet. It also works as a Lightning Address (username@lexe.app) for senders which support LNURL but not BIP 353.

Returns:: A GetHumanBitcoinAddressResponse with the Human Bitcoin Address, the Lightning Address, the BOLT 12 offer that the address resolves to, and whether the username can currently be changed.
Raises:: FfiError – If the request fails.
Return type:: GetHumanBitcoinAddressResponse

Example:

resp = wallet.get_human_bitcoin_address()
print(resp.human_bitcoin_address)

get_payment(index)¶

Get a specific payment by its index.

Parameters:: index (str) – Payment index string (format: <created_at_ms>-<payment_id>).
Returns:: The Payment, or None if not found locally.
Raises:: FfiError – If the index is malformed or the request fails.
Return type:: Payment | None

get_updated_payments(start_index=<object object>, limit=<object object>)¶

Get a batch of payments in ascending updated_at order, starting from a given updated_at index.

Useful for tailing / syncing payment updates as they occur. Fetches directly from the user node (does not read from or write to the local payments cache).

Parameters:

start_index (object | str | None) – The cursor at which the results should start, exclusive. If None, the least recently updated payments will be returned first.
limit (object | int | None) – Maximum number of payments to return. Max 100, defaults to 50.

Returns:

A GetUpdatedPaymentsResponse with the updated payments and an updated_index cursor for fetching the next page.

Raises:

FfiError – If start_index is malformed or the request fails.

Return type:

GetUpdatedPaymentsResponse

Example:

resp = wallet.get_updated_payments()
for p in resp.payments:
    print(f"{p.index}: {p.status}")

# Next page
if resp.updated_index is not None:
    resp = wallet.get_updated_payments(start_index=resp.updated_index)

list_channels()¶

List this node’s Lightning channels.

All of this node’s Lightning channels are connected to the Lexe LSP.

Returns:: A list of ChannelDetails.
Raises:: FfiError – If the node is unreachable.
Return type:: List[ChannelDetails]

Example:

for channel in wallet.list_channels():
    print(f"{channel.channel_id}: {channel.our_balance_sats} sats")

list_clients()¶

List the clients authorized to control this node.

Revoked and expired clients are not included.

Returns:: A dict mapping each client’s hex-encoded public key to its ClientInfo.
Raises:: FfiError – If the request fails.
Return type:: dict[str, ClientInfo]

Example:

for pk, client in wallet.list_clients().items():
    print(f"{pk}: {client.label}")

list_payments(filter, order=<object object>, limit=<object object>, after=<object object>)¶

List payments from local storage with cursor-based pagination.

Reads from the local database only (no network calls). Use sync_payments() to fetch the latest data from the node if needed.

Parameters:

filter (PaymentFilter) – Which payments to include: PaymentFilter.ALL, PaymentFilter.PENDING, PaymentFilter.COMPLETED, PaymentFilter.FAILED, or PaymentFilter.FINALIZED (completed or failed).
order (object | Order | None) – Sort order (Order.DESC or Order.ASC). Defaults to DESC (newest first).
limit (object | int | None) – Maximum number of payments to return. Defaults to 100.
after (object | str | None) – Pagination cursor. Pass next_index from a previous response to get the next page. Defaults to None (first page).

Returns:

A ListPaymentsResponse with payments and a next_index cursor for fetching the next page (None if no more results).

Raises:

FfiError – If after is not a valid payment index string.

Return type:

ListPaymentsResponse

Example:

wallet.sync_payments()

# First page
resp = wallet.list_payments(PaymentFilter.ALL)
for p in resp.payments:
    print(f"{p.index}: {p.amount_sats} sats ({p.status})")

# Next page
if resp.next_index is not None:
    resp = wallet.list_payments(PaymentFilter.ALL, after=resp.next_index)

classmethod load(env_config, credentials, lexe_data_dir=<object object>)¶

Load an existing wallet from local state.

Raises LoadWalletError.NotFound if no local data exists. Use LexeWallet.fresh() to create local state.

Parameters:

env_config (WalletConfig) – Wallet environment configuration.
credentials (Credentials) – Authentication credentials (see Credentials).
lexe_data_dir (object | str | None) – Base data directory (default: ~/.lexe).

Returns:

The loaded LexeWallet instance.

Raises:

LoadWalletError.NotFound – If no local data exists.
LoadWalletError.LoadFailed – If local data is corrupted.

Return type:

Example:

try:
    wallet = LexeWallet.load(config, creds)
except LoadWalletError.NotFound:
    wallet = LexeWallet.fresh(config, creds)

classmethod load_or_fresh(env_config, credentials, lexe_data_dir=<object object>)¶

Load an existing wallet, or create a fresh one if none exists. If you are authenticating with client credentials, this is generally what you want to use.

Parameters:

env_config (WalletConfig) – Wallet environment configuration.
credentials (Credentials) – Authentication credentials (see Credentials).
lexe_data_dir (object | str | None) – Base data directory (default: ~/.lexe).

Returns:

A LexeWallet instance (loaded or newly created).

Raises:

FfiError – If wallet creation fails.

Return type:

node_info()¶

Get information about the node (balance, channels, version).

Returns:: A NodeInfo with the node’s current state.
Raises:: FfiError – If the node is unreachable.
Return type:: NodeInfo

Example:

info = wallet.node_info()
print(f"Balance: {info.balance_sats} sats")
print(f"Channels: {info.num_usable_channels}/{info.num_channels}")

open_channel(value_sats, user_channel_id=<object object>)¶

Open a Lightning channel from this node to Lexe’s LSP.

Parameters:

value_sats (int) – The value of the channel to open, in satoshis.
user_channel_id (object | str | None) – An optional idempotency key, serialized as a 32-character hex string (16 bytes). Retrying with the same id won’t open a duplicate channel. A random id is generated if omitted.

Returns:

An OpenChannelResponse with the ids of the newly opened channel.

Raises:

FfiError – If the channel could not be opened.

Return type:

OpenChannelResponse

Example:

resp = wallet.open_channel(value_sats=100_000)
print(f"Opened channel: {resp.channel_id}")

pay(payable, amount_sats=<object object>, message=<object object>, personal_note=<object object>)¶

Pay any string which encodes a Bitcoin or Lightning payment method.

If there are multiple encoded payment methods, the best recommended one is chosen. For finer control, use analyze() first, then call the specific pay method (pay_invoice(), pay_offer(), etc.).

Supported encodings:

BIP 321 URI: bitcoin:bc1...
Lightning URI: lightning:ln...
BOLT 11 invoice: lnbc1...
BOLT 12 offer: lno1...
Onchain bitcoin address: bc1...
Human Bitcoin Address: ₿username@lexe.app
Lightning Address: username@lexe.app
LNURL: lnurl1... or lnurlp://domain.com/path

Parameters:

payable (str) – The string to pay.
amount_sats (object | int | None) – Amount in satoshis to pay. Required if the payable has no encoded amount. If both the payable and amount_sats specify an amount, they must match. For LNURL payables, the amount must fall within the receiver’s minimum and maximum range.
message (object | str | None) – Optional message to the recipient (BOLT12 offers, LNURL).
personal_note (object | str | None) – Optional personal note (not visible to recipient).

Returns:

The resulting Payment, returned once it reaches a terminal state (completed or failed). Exception: onchain sends return immediately with the payment still in a pending state, since on-chain confirmation takes ~1 hour.

Raises:

FfiError – If the payable string is invalid, the amount is missing or out of range, or payment initiation fails.

Return type:

Example:

payment = wallet.pay("username@lexe.app", amount_sats=1000)
print(f"Payment {payment.status}")

pay_invoice(invoice, fallback_amount_sats=<object object>, personal_note=<object object>)¶

Pay a BOLT 11 Lightning invoice.

Parameters:

invoice (str) – BOLT 11 invoice string to pay.
fallback_amount_sats (object | int | None) – Required if the invoice has no amount encoded.
personal_note (object | str | None) – Optional personal note (not visible to the receiver). If provided, it must be non-empty and <= 200 chars / 512 UTF-8 bytes.

Returns:

The resulting Payment, returned once it reaches a terminal state (completed or failed).

Raises:

FfiError – If the invoice is invalid or payment initiation fails.

Return type:

Example:

payment = wallet.pay_invoice(bolt11_string)
print(f"Payment {payment.status}")

pay_lnurl(lnurl, amount_sats, message=<object object>, personal_note=<object object>)¶

Pay an LNURL via the payRequest flow.

Use analyze() to get the associated LnurlPayRequest, which contains information on amount constraints, message length limits, and more.

Parameters:

lnurl (str) – LNURL string to pay to.
amount_sats (int) – Amount to pay in satoshis. If the LNURL endpoint specifies a minimum or maximum amount, this value must satisfy those limits.
message (object | str | None) – Optional message visible to the recipient. It is only sent if the LNURL endpoint supports it, and is truncated to the endpoint’s length limit if needed.
personal_note (object | str | None) – Optional personal note (not visible to the receiver). If provided, it must be non-empty and no longer than 200 chars / 512 UTF-8 bytes.

Returns:

The resulting Payment, returned once it reaches a terminal state (completed or failed).

Raises:

FfiError – If the LNURL is invalid or payment initiation fails.

Return type:

Example:

payment = wallet.pay_lnurl(lnurl_string, 1000)
print(f"Payment {payment.status}")

pay_offer(offer, amount_sats, message=<object object>, personal_note=<object object>)¶

Pay a BOLT 12 offer over Lightning.

Parameters:

offer (str) – BOLT 12 offer string to pay.
amount_sats (int) – Amount to pay in satoshis.
message (object | str | None) – Optional message visible to the receiver. If provided, it must be non-empty and no longer than 200 chars / 512 UTF-8 bytes.
personal_note (object | str | None) – Optional personal note (not visible to the receiver). If provided, it must be non-empty and no longer than 200 chars / 512 UTF-8 bytes.

Returns:

The resulting Payment, returned once it reaches a terminal state (completed or failed).

Raises:

FfiError – If the offer is invalid or payment initiation fails.

Return type:

Example:

payment = wallet.pay_offer(bolt12_offer, 1000)
print(f"Payment {payment.status}")

provision(credentials)¶

Ensures the wallet is provisioned to all recent trusted releases.

Call every time the wallet is loaded to keep the node running the most up-to-date enclave software.

Parameters:: credentials (Credentials) – Authentication credentials (see Credentials).
Raises:: FfiError – If provisioning fails.
Return type:: None

Example:

wallet = LexeWallet.load_or_fresh(config, creds)
wallet.provision(creds)

revoke_client(client_pk)¶

Permanently revoke a client, making its credentials invalid for authentication. This cannot be undone.

Parameters:: client_pk (str) – Hex-encoded public key of the client to revoke.
Returns:: The revoked ClientInfo.
Raises:: FfiError – If client_pk is malformed or the request fails.
Return type:: ClientInfo

signup(root_seed, partner_pk=<object object>)¶

Call after creating the wallet for the first time. Idempotent: calling again for an already-signed-up user is safe.

Important

After signup, persist the user’s root seed! Without it, users lose access to their funds permanently.

Parameters:

root_seed (RootSeed) – The user’s root seed.
partner_pk (object | str | None) – Optional hex-encoded user public key of your company account. Set to earn a share of fees.

Raises:

FfiError – If signup or provisioning fails.

Return type:

None

Example:

wallet.signup(seed)
seed.write(config)  # Persist seed after signup!

sync_payments()¶

Sync payments from the user node to the local payments cache.

Call periodically to keep local payment data up to date.

Returns:: A PaymentSyncSummary with counts of new and updated payments.
Raises:: FfiError – If the node is unreachable.
Return type:: PaymentSyncSummary

Example:

summary = wallet.sync_payments()
print(f"New: {summary.num_new}, Updated: {summary.num_updated}")

update_client(client_pk, label=<object object>, clear_label=False, expires_at_ms=<object object>, clear_expiration=False)¶

Update a client’s label or expiration. Omitted fields are left as-is.

Parameters:

client_pk (str) – Hex-encoded public key of the client to update.
label (object | str | None) – A new label, or None to leave it unchanged.
clear_label (bool) – Remove the client’s label. Conflicts with label.
expires_at_ms (object | int | None) – A new expiration (ms since UNIX epoch), or None to leave it unchanged.
clear_expiration (bool) – Clear the client’s expiration, so it never expires. Use carefully! Conflicts with expires_at_ms.

Returns:

The updated ClientInfo.

Raises:

FfiError – If client_pk is malformed, the arguments conflict, or the request fails.

Return type:

ClientInfo

update_human_bitcoin_address(username)¶

Claim or update the user’s custom Human Bitcoin Address.

Sets this wallet’s Human Bitcoin Address to ₿{username}@lexe.app and its Lightning Address to {username}@lexe.app. Usernames must be 6 to 24 characters of lowercase alphanumerics and hyphens, and must not start with, end with, or contain consecutive hyphens.

Claiming requires a total wallet balance of at least 10000 sats. Once claimed, the username can be changed for 24 hours, then is frozen for 90 days.

Parameters:: username (str) – The username to claim, e.g. "username" for ₿username@lexe.app.
Returns:: A GetHumanBitcoinAddressResponse with the new Human Bitcoin Address, the Lightning Address, the BOLT 12 offer that the address resolves to, and whether the username can currently be changed.
Raises:: FfiError – If the username is invalid or taken, the wallet balance is below the minimum, or the username is frozen.
Return type:: GetHumanBitcoinAddressResponse

Example:

resp = wallet.update_human_bitcoin_address("username")
print(resp.human_bitcoin_address)

update_personal_note(index, personal_note)¶

Update a payment’s personal note.

Call sync_payments() first so the payment exists locally.

Parameters:

index (str) – Payment index string.
personal_note (str | None) – New personal note text, or None to clear. If provided, it must be non-empty and <= 200 chars / 512 UTF-8 bytes.

Raises:

FfiError – If the payment doesn’t exist locally.

Return type:

None

property user_pk: str¶

Get the user’s hex-encoded public key.

Returns:: The hex-encoded ed25519 user public key string.

Example:

print(f"User PK: {wallet.user_pk}")

wait_for_payment(index, timeout_secs=<object object>)¶

Wait for a payment to reach a terminal state (completed or failed) and return the payment information.

Blocks until the payment finalizes or the timeout is reached. A None timeout waits indefinitely.

Parameters:

index (str) – Payment index string.
timeout_secs (object | int | None) – Maximum wait time in seconds. Waits indefinitely if omitted.

Returns:

The finalized Payment.

Raises:

FfiError – If the timeout is exceeded or the node is unreachable.

Return type:

Example:

resp = wallet.create_invoice(amount_sats=1000)
# Wait until someone pays the invoice (or it expires / fails).
payment = wallet.wait_for_payment(resp.index)
assert payment.status in (PaymentStatus.COMPLETED, PaymentStatus.FAILED)

withdraw_lnurl(lnurl, amount_sats=<object object>, description=<object object>, personal_note=<object object>)¶

Withdraw an LNURL via the withdrawRequest flow.

Use analyze() to get the associated LnurlWithdrawRequest, which contains information on amount constraints, default description, and more.

Parameters:

lnurl (str) – LNURL string to withdraw from.
amount_sats (object | int | None) – Optional amount to withdraw in satoshis. Must satisfy the minimum and maximum limits set by the LNURL endpoint. If None, the maximum amount is withdrawn.
description (object | str | None) – Optional description encoded into the withdrawal invoice and visible to the LNURL endpoint. If None, the description specified by the LNURL endpoint (if any) is used.
personal_note (object | str | None) – Optional private note (not visible to the LNURL endpoint). If provided, it must be non-empty and no longer than 200 chars / 512 UTF-8 bytes.

Returns:

The resulting Payment, returned once the withdrawal reaches a terminal state (completed or failed).

Raises:

FfiError – If the LNURL is invalid or initiating the withdrawal fails.

Return type:

Example:

payment = wallet.withdraw_lnurl(lnurl_string, 1000)
print(f"Payment {payment.status}")

classmethod without_db(env_config, credentials)¶

Create a wallet without local persistence.

Node operations (invoices, payments, node info) work normally. Local payment cache operations (sync_payments(), list_payments(), clear_payments()) are not available and raise if called.

Parameters:

env_config (WalletConfig) – Wallet environment configuration.
credentials (Credentials) – Authentication credentials (see Credentials).

Returns:

A LexeWallet instance without local persistence.

Raises:

FfiError – If wallet creation fails.

Return type:

class lexe.AsyncLexeWallet(*args, **kwargs)¶

Async wallet handle for interacting with a Lexe Lightning node.

For synchronous usage, use LexeWallet.

Example:

from lexe import AsyncLexeWallet, Credentials, RootSeed, WalletConfig

config = WalletConfig.mainnet()
seed = RootSeed.read(config)
creds = Credentials.from_root_seed(seed)

wallet = AsyncLexeWallet.load_or_fresh(config, creds)
await wallet.signup(seed)
await wallet.provision(creds)

info = await wallet.node_info()
print(f"Balance: {info.balance_sats} sats")

classmethod fresh(env_config, credentials, lexe_data_dir=<object object>)¶

Create a fresh wallet, deleting any existing local state for this user.

Data for other users and environments is not affected.

Parameters:

env_config (WalletConfig) – Wallet environment configuration.
credentials (Credentials) – Authentication credentials (see Credentials).
lexe_data_dir (object | str | None) – Base data directory (default: ~/.lexe).

Returns:

A new AsyncLexeWallet instance.

Raises:

FfiError – If wallet creation fails.

Return type:

classmethod load(env_config, credentials, lexe_data_dir=<object object>)¶

Load an existing wallet from local state.

Raises LoadWalletError.NotFound if no local data exists. Use AsyncLexeWallet.fresh() to create local state.

Parameters:

env_config (WalletConfig) – Wallet environment configuration.
credentials (Credentials) – Authentication credentials (see Credentials).
lexe_data_dir (object | str | None) – Base data directory (default: ~/.lexe).

Returns:

The loaded AsyncLexeWallet instance.

Raises:

LoadWalletError.NotFound – If no local data exists.
LoadWalletError.LoadFailed – If local data is corrupted.

Return type:

Example:

try:
    wallet = AsyncLexeWallet.load(config, creds)
except LoadWalletError.NotFound:
    wallet = AsyncLexeWallet.fresh(config, creds)

classmethod load_or_fresh(env_config, credentials, lexe_data_dir=<object object>)¶

Load an existing wallet, or create a fresh one if none exists. If you are authenticating with client credentials, this is generally what you want to use.

Parameters:

env_config (WalletConfig) – Wallet environment configuration.
credentials (Credentials) – Authentication credentials (see Credentials).
lexe_data_dir (object | str | None) – Base data directory (default: ~/.lexe).

Returns:

An AsyncLexeWallet instance (loaded or newly created).

Raises:

FfiError – If wallet creation fails.

Return type:

classmethod without_db(env_config, credentials)¶

Create a wallet without local persistence.

Node operations (invoices, payments, node info) work normally. Local payment cache operations (sync_payments(), list_payments(), clear_payments()) are not available and raise if called.

Parameters:

env_config (WalletConfig) – Wallet environment configuration.
credentials (Credentials) – Authentication credentials (see Credentials).

Returns:

An AsyncLexeWallet instance without local persistence.

Raises:

FfiError – If wallet creation fails.

Return type:

async analyze(payable)¶

Analyze a Bitcoin or Lightning payment string.

Supported encodings:

BIP 321 URI: bitcoin:bc1...
Lightning URI: lightning:ln...
BOLT 11 invoice: lnbc1...
BOLT 12 offer: lno1...
Onchain bitcoin address: bc1...
Human Bitcoin Address: ₿username@lexe.app
Lightning Address: username@lexe.app
LNURL: lnurl1... or lnurlp://domain.com/path

Within the encodings, the following payment methods are supported:

BOLT 11 invoice
BOLT 12 offer
Bitcoin address
Lightning Address
LNURL-pay

And the following claim methods are supported:

LNURL-withdraw

Parameters:: payable (str) – The string-encoded payment method.
Returns:: An AnalyzeResponse with payables (outbound payment routes, sorted from most to least recommended) and claimables (inbound claim routes, e.g. LNURL-withdraw).
Raises:: FfiError – If no valid payment methods were found.
Return type:: AnalyzeResponse

Example:

resp = await wallet.analyze("username@lexe.app")
details = resp.payables[0]
print(details.payable)         # "https://lexe.app/.well-known/lnurlp/satoshi"
print(details.method)          # PaymentMethod.LNURL_PAY(...)
print(details.min_amount_sats) # minimum payable amount
print(details.max_amount_sats) # maximum payable amount

async buy_with_cash_app(amount_sats)¶

Buy Bitcoin with Cash App.

Given an amount of Bitcoin that the user wants to buy, returns a Cash App URL that you can redirect your user to complete the purchase. Cash App buys are instant and land directly into Lexe wallet.

Parameters:: amount_sats (int) – Amount of Bitcoin to buy in satoshis. Must be at least 5000.
Returns:: A CashAppBuyResponse whose redirect_url you should send your user to, to complete the purchase. For the smoothest experience, encourage them to open it on a device where Cash App is already set up.
Raises:: FfiError – If the amount is below the minimum or the request fails.
Return type:: CashAppBuyResponse

Example:

resp = await wallet.buy_with_cash_app(5000)
print(resp.redirect_url)  # Redirect your user here

clear_payments()¶

Clear all locally cached payment data for this wallet.

Clears the local payment cache only. Remote data on the node is not affected. Call sync_payments() to re-populate.

Raises:: FfiError – If the local database cannot be cleared.
Return type:: None

async close_channel(channel_id)¶

Close a Lightning channel.

Parameters:: channel_id (str) – The id of the channel to close, serialized as a 64-character hex string (32 bytes).
Raises:: FfiError – If the channel could not be closed.
Return type:: None

Example:

await wallet.close_channel(channel_id)

async create_client(expires_at_ms, label=<object object>)¶

Create a new client authorized to control this node.

The returned credentials grant control of this node without exposing the root seed, and can be revoked at any time with revoke_client().

Warning

Anyone with the returned credentials can control this node’s funds. Store them somewhere safe.

Parameters:

expires_at_ms (int | None) – The client’s expiration (ms since UNIX epoch), or None for a client that never expires. Use carefully!
label (object | str | None) – An optional label of at most 64 UTF-8 bytes.

Returns:

A CreateClientResponse with the new client’s public key and credentials.

Raises:

FfiError – If the request fails.

Return type:

CreateClientResponse

Example:

# Pass expires_at_ms=None to opt into a never-expiring client.
resp = await wallet.create_client(expires_at_ms=None, label="my-server")
# Store the credentials somewhere safe; reload later with
# ClientCredentials.from_string(...).
creds_str = resp.client_credentials.export_string()

async create_invoice(expiration_secs=<object object>, amount_sats=<object object>, description=<object object>, personal_note=<object object>, partner_pk=<object object>, partner_prop_fee_ppm=<object object>, partner_base_fee_sats=<object object>)¶

Create a BOLT 11 Lightning invoice.

Parameters:

expiration_secs (object | int | None) – Invoice expiry in seconds (e.g. 3600 for 1 hour), or None for a default of 86400 (1 day).
amount_sats (object | int | None) – Amount in satoshis, or None for an amountless invoice.
description (object | str | None) – Optional description shown to the payer.
personal_note (object | str | None) – Optional personal note (not visible to the payer). If provided, it must be non-empty and <= 200 chars / 512 UTF-8 bytes.
partner_pk (object | str | None) – Hex-encoded user_pk of a Lexe partner setting custom fees. Must be set for partner fee fields to take effect.
partner_prop_fee_ppm (object | int | None) – Partner proportional fee in parts per million (ppm). Must be set if partner_pk is set. Min: 5000, Max: 500000 (50%).
partner_base_fee_sats (object | int | None) – Partner base fee in satoshis. If set, amount_sats must also be set.

Returns:

A CreateInvoiceResponse with the invoice string and metadata.

Raises:

FfiError – If the node is offline or the request fails.

Return type:

CreateInvoiceResponse

Example:

resp = await wallet.create_invoice(3600, 1000, "Coffee")
print(resp.invoice)      # BOLT 11 invoice string
print(resp.amount_sats)  # 1000

async create_offer(description=<object object>, min_amount_sats=<object object>, expiration_secs=<object object>)¶

Create a BOLT 12 offer to receive Lightning payments.

Unlike invoices, offers are reusable: multiple payments can be made to it, including from multiple payers.

Parameters:

description (object | str | None) – Optional description shown to the sender when they scan the offer. If provided, it must be non-empty and no longer than 200 chars / 512 UTF-8 bytes.
min_amount_sats (object | int | None) – Optional minimum payment amount in satoshis.
expiration_secs (object | int | None) – Optional expiration time in seconds from now.

Returns:

A CreateOfferResponse with the BOLT 12 offer string.

Raises:

FfiError – If the node is offline or the request fails.

Return type:

CreateOfferResponse

Example:

resp = await wallet.create_offer(description="Donations")
print(resp.offer)  # BOLT 12 offer string

async get_human_bitcoin_address()¶

Get the user’s Human Bitcoin Address.

Returns:: A GetHumanBitcoinAddressResponse with the Human Bitcoin Address, the Lightning Address, the BOLT 12 offer that the address resolves to, and whether the username can currently be changed.
Raises:: FfiError – If the request fails.
Return type:: GetHumanBitcoinAddressResponse

Example:

resp = await wallet.get_human_bitcoin_address()
print(resp.human_bitcoin_address)

async get_payment(index)¶

Get a specific payment by its index.

Parameters:: index (str) – Payment index string (format: <created_at_ms>-<payment_id>).
Returns:: The Payment, or None if not found locally.
Raises:: FfiError – If the index is malformed or the request fails.
Return type:: Payment | None

async get_updated_payments(start_index=<object object>, limit=<object object>)¶

Get a batch of payments in ascending updated_at order, starting from a given updated_at index.

Useful for tailing / syncing payment updates as they occur. Fetches directly from the user node (does not read from or write to the local payments cache).

Parameters:

start_index (object | str | None) – The cursor at which the results should start, exclusive. If None, the least recently updated payments will be returned first.
limit (object | int | None) – Maximum number of payments to return. Max 100, defaults to 50.

Returns:

A GetUpdatedPaymentsResponse with the updated payments and an updated_index cursor for fetching the next page.

Raises:

FfiError – If start_index is malformed or the request fails.

Return type:

GetUpdatedPaymentsResponse

Example:

resp = await wallet.get_updated_payments()
for p in resp.payments:
    print(f"{p.index}: {p.status}")

# Next page
if resp.updated_index is not None:
    resp = await wallet.get_updated_payments(start_index=resp.updated_index)

async list_channels()¶

List this node’s Lightning channels.

All of this node’s Lightning channels are connected to the Lexe LSP.

Returns:: A list of ChannelDetails.
Raises:: FfiError – If the node is unreachable.
Return type:: List[ChannelDetails]

Example:

for channel in await wallet.list_channels():
    print(f"{channel.channel_id}: {channel.our_balance_sats} sats")

async list_clients()¶

List the clients authorized to control this node.

Revoked and expired clients are not included.

Returns:: A dict mapping each client’s hex-encoded public key to its ClientInfo.
Raises:: FfiError – If the request fails.
Return type:: dict[str, ClientInfo]

Example:

for pk, client in (await wallet.list_clients()).items():
    print(f"{pk}: {client.label}")

list_payments(filter, order=<object object>, limit=<object object>, after=<object object>)¶

List payments from local storage with cursor-based pagination.

Reads from the local database only (no network calls). Use sync_payments() to fetch the latest data from the node if needed.

Parameters:

filter (PaymentFilter) – Which payments to include: PaymentFilter.ALL, PaymentFilter.PENDING, PaymentFilter.COMPLETED, PaymentFilter.FAILED, or PaymentFilter.FINALIZED (completed or failed).
order (object | Order | None) – Sort order (Order.DESC or Order.ASC). Defaults to DESC (newest first).
limit (object | int | None) – Maximum number of payments to return. Defaults to 100.
after (object | str | None) – Pagination cursor. Pass next_index from a previous response to get the next page. Defaults to None (first page).

Returns:

A ListPaymentsResponse with payments and a next_index cursor for fetching the next page (None if no more results).

Raises:

FfiError – If after is not a valid payment index string.

Return type:

ListPaymentsResponse

Example:

await wallet.sync_payments()

# First page
resp = wallet.list_payments(PaymentFilter.ALL)
for p in resp.payments:
    print(f"{p.index}: {p.amount_sats} sats ({p.status})")

# Next page
if resp.next_index is not None:
    resp = wallet.list_payments(PaymentFilter.ALL, after=resp.next_index)

async node_info()¶

Get information about the node (balance, channels, version).

Returns:: A NodeInfo with the node’s current state.
Raises:: FfiError – If the node is unreachable.
Return type:: NodeInfo

Example:

info = await wallet.node_info()
print(f"Balance: {info.balance_sats} sats")
print(f"Channels: {info.num_usable_channels}/{info.num_channels}")

async open_channel(value_sats, user_channel_id=<object object>)¶

Open a Lightning channel from this node to Lexe’s LSP.

Parameters:

value_sats (int) – The value of the channel to open, in satoshis.
user_channel_id (object | str | None) – An optional idempotency key, serialized as a 32-character hex string (16 bytes). Retrying with the same id won’t open a duplicate channel. A random id is generated if omitted.

Returns:

An OpenChannelResponse with the ids of the newly opened channel.

Raises:

FfiError – If the channel could not be opened.

Return type:

OpenChannelResponse

Example:

resp = await wallet.open_channel(value_sats=100_000)
print(f"Opened channel: {resp.channel_id}")

async pay(payable, amount_sats=<object object>, message=<object object>, personal_note=<object object>)¶

Pay any string which encodes a Bitcoin or Lightning payment method.

If there are multiple encoded payment methods, the best recommended one is chosen. For finer control, use analyze() first, then call the specific pay method (pay_invoice(), pay_offer(), etc.).

Supported encodings:

BIP 321 URI: bitcoin:bc1...
Lightning URI: lightning:ln...
BOLT 11 invoice: lnbc1...
BOLT 12 offer: lno1...
Onchain bitcoin address: bc1...
Human Bitcoin Address: ₿username@lexe.app
Lightning Address: username@lexe.app
LNURL: lnurl1... or lnurlp://domain.com/path

Parameters:

payable (str) – The string to pay.
amount_sats (object | int | None) – Amount in satoshis to pay. Required if the payable has no encoded amount. If both the payable and amount_sats specify an amount, they must match. For LNURL payables, the amount must fall within the receiver’s minimum and maximum range.
message (object | str | None) – Optional message to the recipient (BOLT12 offers, LNURL).
personal_note (object | str | None) – Optional personal note (not visible to recipient).

Returns:

Raises:

FfiError – If the payable string is invalid, the amount is missing or out of range, or payment initiation fails.

Return type:

Example:

payment = await wallet.pay("username@lexe.app", amount_sats=1000)
print(f"Payment {payment.status}")

async pay_invoice(invoice, fallback_amount_sats=<object object>, personal_note=<object object>)¶

Pay a BOLT 11 Lightning invoice.

Parameters:

invoice (str) – BOLT 11 invoice string to pay.
fallback_amount_sats (object | int | None) – Required if the invoice has no amount encoded.
personal_note (object | str | None) – Optional personal note (not visible to the receiver). If provided, it must be non-empty and <= 200 chars / 512 UTF-8 bytes.

Returns:

The resulting Payment, returned once it reaches a terminal state (completed or failed).

Raises:

FfiError – If the invoice is invalid or payment initiation fails.

Return type:

Example:

payment = await wallet.pay_invoice(bolt11_string)
print(f"Payment {payment.status}")

async pay_lnurl(lnurl, amount_sats, message=<object object>, personal_note=<object object>)¶

Pay an LNURL via the payRequest flow.

Use analyze() to get the associated LnurlPayRequest, which contains information on amount constraints, message length limits, and more.

Parameters:

lnurl (str) – LNURL string to pay to.
amount_sats (int) – Amount to pay in satoshis. If the LNURL endpoint specifies a minimum or maximum amount, this value must satisfy those limits.
message (object | str | None) – Optional message visible to the recipient. It is only sent if the LNURL endpoint supports it, and is truncated to the endpoint’s length limit if needed.
personal_note (object | str | None) – Optional personal note (not visible to the receiver). If provided, it must be non-empty and no longer than 200 chars / 512 UTF-8 bytes.

Returns:

The resulting Payment, returned once it reaches a terminal state (completed or failed).

Raises:

FfiError – If the LNURL is invalid or payment initiation fails.

Return type:

Example:

payment = await wallet.pay_lnurl(lnurl_string, 1000)
print(f"Payment {payment.status}")

async pay_offer(offer, amount_sats, message=<object object>, personal_note=<object object>)¶

Pay a BOLT 12 offer over Lightning.

Parameters:

offer (str) – BOLT 12 offer string to pay.
amount_sats (int) – Amount to pay in satoshis.
message (object | str | None) – Optional message visible to the receiver. If provided, it must be non-empty and no longer than 200 chars / 512 UTF-8 bytes.
personal_note (object | str | None) – Optional personal note (not visible to the receiver). If provided, it must be non-empty and no longer than 200 chars / 512 UTF-8 bytes.

Returns:

The resulting Payment, returned once it reaches a terminal state (completed or failed).

Raises:

FfiError – If the offer is invalid or payment initiation fails.

Return type:

Example:

payment = await wallet.pay_offer(bolt12_offer, 1000)
print(f"Payment {payment.status}")

async provision(credentials)¶

Ensures the wallet is provisioned to all recent trusted releases.

Call every time the wallet is loaded to keep the node running the most up-to-date enclave software.

Parameters:: credentials (Credentials) – Authentication credentials (see Credentials).
Raises:: FfiError – If provisioning fails.
Return type:: None

Example:

wallet = AsyncLexeWallet.load_or_fresh(config, creds)
await wallet.provision(creds)

async revoke_client(client_pk)¶

Permanently revoke a client, making its credentials invalid for authentication. This cannot be undone.

Parameters:: client_pk (str) – Hex-encoded public key of the client to revoke.
Returns:: The revoked ClientInfo.
Raises:: FfiError – If client_pk is malformed or the request fails.
Return type:: ClientInfo

async signup(root_seed, partner_pk=<object object>)¶

Call after creating the wallet for the first time. Idempotent: calling again for an already-signed-up user is safe.

Important

After signup, persist the user’s root seed! Without it, users lose access to their funds permanently.

Parameters:

root_seed (RootSeed) – The user’s root seed.
partner_pk (object | str | None) – Optional hex-encoded user public key of your company account. Set to earn a share of fees.

Raises:

FfiError – If signup or provisioning fails.

Return type:

None

Example:

await wallet.signup(seed)
seed.write(config)  # Persist seed after signup!

async sync_payments()¶

Sync payments from the user node to the local payments cache.

Call periodically to keep local payment data up to date.

Returns:: A PaymentSyncSummary with counts of new and updated payments.
Raises:: FfiError – If the node is unreachable.
Return type:: PaymentSyncSummary

Example:

summary = await wallet.sync_payments()
print(f"New: {summary.num_new}, Updated: {summary.num_updated}")

async update_client(client_pk, label=<object object>, clear_label=False, expires_at_ms=<object object>, clear_expiration=False)¶

Update a client’s label or expiration. Omitted fields are left as-is.

Parameters:

client_pk (str) – Hex-encoded public key of the client to update.
label (object | str | None) – A new label, or None to leave it unchanged.
clear_label (bool) – Remove the client’s label. Conflicts with label.
expires_at_ms (object | int | None) – A new expiration (ms since UNIX epoch), or None to leave it unchanged.
clear_expiration (bool) – Clear the client’s expiration, so it never expires. Use carefully! Conflicts with expires_at_ms.

Returns:

The updated ClientInfo.

Raises:

FfiError – If client_pk is malformed, the arguments conflict, or the request fails.

Return type:

ClientInfo

async update_human_bitcoin_address(username)¶

Claim or update the user’s custom Human Bitcoin Address.

Claiming requires a total wallet balance of at least 10000 sats. Once claimed, the username can be changed for 24 hours, then is frozen for 90 days.

Parameters:: username (str) – The username to claim, e.g. "username" for ₿username@lexe.app.
Returns:: A GetHumanBitcoinAddressResponse with the new Human Bitcoin Address, the Lightning Address, the BOLT 12 offer that the address resolves to, and whether the username can currently be changed.
Raises:: FfiError – If the username is invalid or taken, the wallet balance is below the minimum, or the username is frozen.
Return type:: GetHumanBitcoinAddressResponse

Example:

resp = await wallet.update_human_bitcoin_address("username")
print(resp.human_bitcoin_address)

async update_personal_note(index, personal_note)¶

Update a payment’s personal note.

Call sync_payments() first so the payment exists locally.

Parameters:

index (str) – Payment index string.
personal_note (str | None) – New personal note text, or None to clear. If provided, it must be non-empty and <= 200 chars / 512 UTF-8 bytes.

Raises:

FfiError – If the payment doesn’t exist locally.

Return type:

None

property user_pk: str¶

Get the user’s hex-encoded public key.

Returns:: The hex-encoded ed25519 user public key string.

Example:

print(f"User PK: {wallet.user_pk}")

async wait_for_payment(index, timeout_secs=<object object>)¶

Wait for a payment to reach a terminal state (completed or failed) and return the payment information.

Blocks until the payment finalizes or the timeout is reached. A None timeout waits indefinitely.

Parameters:

index (str) – Payment index string.
timeout_secs (object | int | None) – Maximum wait time in seconds. Waits indefinitely if omitted.

Returns:

The finalized Payment.

Raises:

FfiError – If the timeout is exceeded or the node is unreachable.

Return type:

Example:

resp = await wallet.create_invoice(amount_sats=1000)
# Wait until someone pays the invoice (or it expires / fails).
payment = await wallet.wait_for_payment(resp.index)
assert payment.status in (PaymentStatus.COMPLETED, PaymentStatus.FAILED)

async withdraw_lnurl(lnurl, amount_sats=<object object>, description=<object object>, personal_note=<object object>)¶

Withdraw an LNURL via the withdrawRequest flow.

Use analyze() to get the associated LnurlWithdrawRequest, which contains information on amount constraints, default description, and more.

Parameters:

lnurl (str) – LNURL string to withdraw from.
amount_sats (object | int | None) – Optional amount to withdraw in satoshis. Must satisfy the minimum and maximum limits set by the LNURL endpoint. If None, the maximum amount is withdrawn.
description (object | str | None) – Optional description encoded into the withdrawal invoice and visible to the LNURL endpoint. If None, the description specified by the LNURL endpoint (if any) is used.
personal_note (object | str | None) – Optional private note (not visible to the LNURL endpoint). If provided, it must be non-empty and no longer than 200 chars / 512 UTF-8 bytes.

Returns:

The resulting Payment, returned once the withdrawal reaches a terminal state (completed or failed).

Raises:

FfiError – If the LNURL is invalid or initiating the withdrawal fails.

Return type: