Lexe Python SDK¶

Configuration¶

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

Configuration for a wallet environment.

Use the factory constructors to create configs for standard environments.

Example:

# Production (mainnet)
config = WalletConfig.mainnet()

# Staging (testnet)
config = WalletConfig.testnet3()

# Local development (regtest)
config = WalletConfig.regtest()
config = WalletConfig.regtest(use_sgx=True, gateway_url="http://localhost:8080")

classmethod mainnet()¶

Create a config for mainnet (production).

Returns:

A WalletConfig for the mainnet environment.

Return type:

WalletConfig

classmethod regtest(use_sgx=False, gateway_url=<object object>)¶

Create a config for regtest (local development).

Parameters:

• use_sgx (bool) – Whether SGX is enabled. Defaults to False.

• gateway_url (object | str | None) – Gateway URL override, or None for default.

Returns:

A WalletConfig for the regtest environment.

Return type:

WalletConfig

classmethod testnet3()¶

Create a config for testnet3 (staging).

Returns:

A WalletConfig for the testnet3 environment.

Return type:

WalletConfig

property deploy_env: DeployEnv¶

Get the configured deployment environment.

Returns:

The DeployEnv for this config.

property gateway_url: str | None¶

Get the gateway URL for this environment.

Returns:

The gateway URL string, or None if using the default.

property network: Network¶

Get the configured Bitcoin network.

Returns:

The Network for this config.

seedphrase_path(lexe_data_dir=<object object>)¶

Returns the path to the seedphrase file for this environment.

• Mainnet: <lexe_data_dir>/seedphrase.txt

• Other environments: <lexe_data_dir>/seedphrase.<env>.txt

Parameters:

lexe_data_dir (object | str | None) – Base data directory path. Defaults to ~/.lexe.

Returns:

The absolute path to the seedphrase file.

Return type:

str

Example:

config = WalletConfig.mainnet()
path = config.seedphrase_path()
# '/home/user/.lexe/seedphrase.txt'

property use_sgx: bool¶

Whether SGX is enabled for this config.

Returns:

True if SGX is enabled, False otherwise.

class lexe.DeployEnv(*values)¶

Deployment environment for a wallet.

• DEV – Development environment (local regtest).

• STAGING – Staging environment (testnet).

• PROD – Production environment (mainnet).

DEV = 0¶

Development environment.

STAGING = 1¶

Staging environment.

PROD = 2¶

Production environment.

class lexe.Network(*values)¶

Bitcoin network to use.

• MAINNET – Bitcoin mainnet.

• TESTNET3 – Bitcoin testnet3.

• TESTNET4 – Bitcoin testnet4.

• SIGNET – Bitcoin signet.

• REGTEST – Bitcoin regtest (local development).

MAINNET = 0¶

Bitcoin mainnet.

TESTNET3 = 1¶

Bitcoin testnet3.

TESTNET4 = 2¶

Bitcoin testnet4.

SIGNET = 3¶

Bitcoin signet.

REGTEST = 4¶

Bitcoin regtest.

Credentials¶

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

The secret root seed for deriving all user keys and credentials.

Create with RootSeed.generate(), from raw bytes with RootSeed.from_bytes(), or load from a file with RootSeed.read() or RootSeed.read_from_path().

Example:

# Generate a new random seed
seed = RootSeed.generate()

# Or create from raw bytes
import os
seed = RootSeed.from_bytes(os.urandom(32))

# Or load from the default seedphrase path for this environment
config = WalletConfig.mainnet()
seed = RootSeed.read(config)

# Or load from a specific file path
seed = RootSeed.read_from_path("/home/user/.lexe/seedphrase.txt")

classmethod from_bytes(seed_bytes)¶

Construct a root seed from raw bytes. The seed must be exactly 32 bytes.

Parameters:

seed_bytes (bytes) – Raw 32-byte seed.

Returns:

A RootSeed from the given bytes.

Raises:

FfiError – If the input is not exactly 32 bytes.

Return type:

RootSeed

Example:

import os
seed = RootSeed.from_bytes(os.urandom(32))

classmethod from_hex(hex_string)¶

Construct a root seed from a 64-character hex string.

Parameters:

hex_string (str) – 64-character hex-encoded seed.

Returns:

A RootSeed from the given hex string.

Raises:

FfiError – If the hex string is invalid or the wrong length.

Return type:

RootSeed

Example:

seed = RootSeed.from_hex("a1b2c3...")

classmethod from_mnemonic(mnemonic)¶

Construct a root seed from a BIP39 mnemonic string.

Parameters:

mnemonic (str) – Space-separated BIP39 mnemonic words.

Returns:

The root seed derived from the mnemonic.

Raises:

FfiError – If the mnemonic is invalid.

Return type:

RootSeed

Example:

seed = RootSeed.from_mnemonic("abandon abandon ... about")

classmethod generate()¶

Generate a new random root seed.

Returns:

A new randomly-generated RootSeed.

Return type:

RootSeed

Example:

seed = RootSeed.generate()

classmethod password_decrypt(password, encrypted)¶

Decrypt a password-encrypted root seed.

Parameters:

• password (str) – The password used to encrypt.

• encrypted (bytes) – The encrypted seed bytes.

Returns:

The decrypted RootSeed.

Raises:

FfiError – If decryption fails (wrong password or corrupted data).

Return type:

RootSeed

Example:

encrypted = seed.password_encrypt("my-password")
decrypted = RootSeed.password_decrypt("my-password", encrypted)

classmethod read(env_config)¶

Reads a root seed from ~/.lexe/seedphrase[.env].txt.

Parameters:

env_config (WalletConfig) – The wallet environment config.

Returns:

The root seed loaded from the file.

Raises:

• SeedFileError.NotFound – If the seedphrase file doesn’t exist.

• SeedFileError.ParseError – If the file exists but cannot be parsed.

Return type:

RootSeed

Example:

config = WalletConfig.mainnet()
try:
    seed = RootSeed.read(config)
except SeedFileError.NotFound:
    seed = RootSeed.from_bytes(os.urandom(32))

classmethod read_from_path(path)¶

Reads a root seed from a seedphrase file containing a BIP39 mnemonic.

Parameters:

path (str) – Absolute path to the seedphrase file.

Returns:

The root seed loaded from the file.

Raises:

• SeedFileError.NotFound – If the file doesn’t exist.

• SeedFileError.ParseError – If the file cannot be parsed.

Return type:

RootSeed

Example:

try:
    seed = RootSeed.read_from_path("/home/user/.lexe/seedphrase.txt")
except SeedFileError.NotFound:
    seed = RootSeed.from_bytes(os.urandom(32))

derive_node_pk()¶

Derive the node public key.

Returns:

The hex-encoded secp256k1 node public key string.

Return type:

str

Example:

seed = RootSeed.generate()
print(f"Node PK: {seed.derive_node_pk()}")

derive_user_pk()¶

Derive the user’s public key.

Returns:

The hex-encoded ed25519 user public key string.

Return type:

str

Example:

seed = RootSeed.generate()
print(f"User PK: {seed.derive_user_pk()}")

password_encrypt(password)¶

Encrypt this root seed under the given password.

Parameters:

password (str) – The password to encrypt with.

Returns:

The encrypted seed as bytes.

Raises:

FfiError – If encryption fails.

Return type:

bytes

Example:

encrypted = seed.password_encrypt("my-password")

to_bytes()¶

Return the 32-byte root seed.

Returns:

The raw seed bytes.

Return type:

bytes

to_hex()¶

Encode the root secret as a 64-character hex string.

Returns:

The hex-encoded seed string.

Return type:

str

to_mnemonic()¶

Return this root seed’s mnemonic as a space-separated string.

Returns:

The BIP39 mnemonic string.

Return type:

str

Example:

seed = RootSeed.generate()
print(seed.to_mnemonic())

write(env_config)¶

Writes this root seed’s mnemonic to ~/.lexe/seedphrase[.env].txt.

Creates parent directories if needed.

Parameters:

env_config (WalletConfig) – The wallet environment config.

Raises:

• SeedFileError.AlreadyExists – If the file already exists.

• SeedFileError.IoError – If the file cannot be written.

Return type:

None

Example:

config = WalletConfig.mainnet()
seed.write(config)

write_to_path(path)¶

Writes this root seed’s mnemonic to the given file path.

Creates parent directories if needed.

Parameters:

path (str) – Absolute path to write the seedphrase file.

Raises:

• SeedFileError.AlreadyExists – If the file already exists.

• SeedFileError.IoError – If the file cannot be written.

Return type:

None

Example:

seed = RootSeed.from_bytes(os.urandom(32))
seed.write_to_path("/home/user/.lexe/seedphrase.txt")

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

Scoped and revocable credentials for controlling a Lexe user node.

These are useful when you want node access without exposing the user’s RootSeed, which is irrevocable. Wrap into Credentials to use with wallet constructors.

from_string(s)¶

Parse credentials from a portable string.

Parameters:

s (str)

Return type:

ClientCredentials

export_string()¶

Export credentials as a portable string (round-trips with from_string).

Return type:

str

classmethod from_string(s)¶

Parse client credentials from a string.

Parameters:

s (str)

Return type:

ClientCredentials

export_string()¶

Export these credentials as a portable string.

The returned string can be passed to [ClientCredentials::from_string] to reconstruct the credentials.

Return type:

str

Wallet¶

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

Synchronous wallet handle for interacting with a Lexe Lightning node.

For async usage, use AsyncLexeWallet.

Create a wallet using one of the constructors:

• load() – Load from existing local state.

• fresh() – Create fresh local state (deletes existing).

• load_or_fresh() – Load or create if none exists.

Then call signup() and provision() before using payment methods.

Example:

config = WalletConfig.mainnet()
seed = RootSeed.read(config)  # Raises SeedFileError.NotFound if missing
creds = Credentials.from_root_seed(seed)

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

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

clear_payments()¶

Clear all local 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

create_invoice(expiration_secs, amount_sats=<object object>, description=<object object>, payer_note=<object object>)¶

Create a BOLT11 Lightning invoice.

Parameters:

• expiration_secs (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.

• payer_note (object | str | None) – Optional note received from the payer out-of-band via LNURL-pay that is stored with this payment. If provided, it must be non-empty and <= 200 chars / 512 UTF-8 bytes.

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 = wallet.create_invoice(3600, 1000, "Coffee")
print(resp.invoice)      # BOLT11 invoice string
print(resp.amount_sats)  # 1000

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 LexeWallet instance.

Raises:

FfiError – If wallet creation fails.

Return type:

LexeWallet

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

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:

LexeWallet

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:

LexeWallet

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}")

pay_invoice(invoice, fallback_amount_sats=<object object>, note=<object object>, payer_note=<object object>)¶

Pay a BOLT11 Lightning invoice.

Parameters:

• invoice (str) – BOLT11 invoice string to pay.

• fallback_amount_sats (object | int | None) – Required if the invoice has no amount encoded.

• note (object | str | None) – Optional private note (not visible to the receiver). If provided, it must be non-empty and <= 200 chars / 512 UTF-8 bytes.

• payer_note (object | str | None) – Optional note that was sent to the receiver via LNURL-pay and is visible to them. If provided, it must be non-empty and <= 200 chars / 512 UTF-8 bytes.

Returns:

A PayInvoiceResponse with the payment index and timestamp.

Raises:

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

Return type:

PayInvoiceResponse

Example:

resp = wallet.pay_invoice(bolt11_string)
payment = wallet.wait_for_payment(resp.index)
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 user 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)

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

Register this user with Lexe and provision their node.

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 remote node to local storage.

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_payment_note(index, note)¶

Update a payment’s personal note.

Call sync_payments() first so the payment exists locally.

Parameters:

• index (str) – Payment index string.

• note (str | None) – New 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).

Polls the node with exponential backoff until the payment finalizes or the timeout is reached. Defaults to 10 minutes if not specified. Maximum timeout is 86,400 seconds (24 hours).

Parameters:

• index (str) – Payment index string.

• timeout_secs (object | int | None) – Maximum wait time in seconds. Defaults to 600. Max: 86400 (24 hours).

Returns:

The finalized Payment.

Raises:

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

Return type:

Payment

Example:

resp = wallet.pay_invoice(invoice_str)
payment = wallet.wait_for_payment(resp.index)
assert payment.status in (PaymentStatus.COMPLETED, PaymentStatus.FAILED)

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 will return an error if called.

Parameters:

• env_config (WalletConfig)

• credentials (Credentials)

Return type:

LexeWallet

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, 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:

AsyncLexeWallet

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:

AsyncLexeWallet

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:

AsyncLexeWallet

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 will return an error if called.

Parameters:

• env_config (WalletConfig)

• credentials (Credentials)

Return type:

AsyncLexeWallet

clear_payments()¶

Clear all local 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 create_invoice(expiration_secs=<object object>, amount_sats=<object object>, description=<object object>, payer_note=<object object>)¶

Create a BOLT11 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.

• payer_note (object | str | None) – Optional note received from the payer out-of-band via LNURL-pay that is stored with this payment. If provided, it must be non-empty and <= 200 chars / 512 UTF-8 bytes.

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)      # BOLT11 invoice string
print(resp.amount_sats)  # 1000

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

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 pay_invoice(invoice, fallback_amount_sats=<object object>, note=<object object>, payer_note=<object object>)¶

Pay a BOLT11 Lightning invoice.

Parameters:

• invoice (str) – BOLT11 invoice string to pay.

• fallback_amount_sats (object | int | None) – Required if the invoice has no amount encoded.

• note (object | str | None) – Optional private note (not visible to the receiver). If provided, it must be non-empty and <= 200 chars / 512 UTF-8 bytes.

• payer_note (object | str | None) – Optional note that was sent to the receiver via LNURL-pay and is visible to them. If provided, it must be non-empty and <= 200 chars / 512 UTF-8 bytes.

Returns:

A PayInvoiceResponse with the payment index and timestamp.

Raises:

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

Return type:

PayInvoiceResponse

Example:

resp = await wallet.pay_invoice(bolt11_string)
payment = await wallet.wait_for_payment(resp.index)
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 user 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 signup(root_seed, partner_pk=<object object>)¶

Register this user with Lexe and provision their node.

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 remote node to local storage.

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_payment_note(index, note)¶

Update a payment’s personal note.

Call sync_payments() first so the payment exists locally.

Parameters:

• index (str) – Payment index string.

• note (str | None) – New 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).

Polls the node with exponential backoff until the payment finalizes or the timeout is reached. Defaults to 10 minutes if not specified. Maximum timeout is 86,400 seconds (24 hours).

Parameters:

• index (str) – Payment index string.

• timeout_secs (object | int | None) – Maximum wait time in seconds. Defaults to 600. Max: 86400 (24 hours).

Returns:

The finalized Payment.

Raises:

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

Return type:

Payment

Example:

resp = await wallet.pay_invoice(invoice_str)
payment = await wallet.wait_for_payment(resp.index)
assert payment.status in (PaymentStatus.COMPLETED, PaymentStatus.FAILED)

class lexe.NodeInfo(*, version, measurement, user_pk, node_pk, balance_sats, lightning_balance_sats, lightning_sendable_balance_sats, lightning_max_sendable_balance_sats, onchain_balance_sats, onchain_trusted_balance_sats, num_channels, num_usable_channels)¶

Information about a Lexe Lightning node.

Parameters:

• version (str)

• measurement (str)

• user_pk (str)

• node_pk (str)

• balance_sats (int)

• lightning_balance_sats (int)

• lightning_sendable_balance_sats (int)

• lightning_max_sendable_balance_sats (int)

• onchain_balance_sats (int)

• onchain_trusted_balance_sats (int)

• num_channels (int)

• num_usable_channels (int)

version¶

Node’s current semver version, e.g. "0.6.9".

measurement¶

Hex-encoded SGX measurement of the current node.

user_pk¶

Hex-encoded ed25519 user public key.

node_pk¶

Hex-encoded secp256k1 node public key (“node_id”).

balance_sats¶

Total balance in sats (Lightning + on-chain).

lightning_balance_sats¶

Total Lightning balance in sats.

lightning_sendable_balance_sats¶

Estimated Lightning sendable balance in sats.

lightning_max_sendable_balance_sats¶

Maximum Lightning sendable balance in sats.

onchain_balance_sats¶

Total on-chain balance in sats (includes unconfirmed).

onchain_trusted_balance_sats¶

Trusted on-chain balance in sats.

num_channels¶

Total number of Lightning channels.

num_usable_channels¶

Number of usable Lightning channels.

Payments¶

class lexe.Payment(*, index, created_at_ms, updated_at_ms, rail, kind, direction, status, status_msg, amount_sats, fees_sats, note, invoice, txid, address, expires_at_ms, finalized_at_ms, payer_name, payer_note, priority)¶

Information about a payment.

Parameters:

• index (str)

• created_at_ms (int)

• updated_at_ms (int)

• rail (PaymentRail)

• kind (PaymentKind)

• direction (PaymentDirection)

• status (PaymentStatus)

• status_msg (str)

• amount_sats (Optional[int])

• fees_sats (int)

• note (Optional[str])

• invoice (Optional[Invoice])

• txid (Optional[str])

• address (Optional[str])

• expires_at_ms (Optional[int])

• finalized_at_ms (Optional[int])

• payer_name (Optional[str])

• payer_note (Optional[str])

• priority (Optional[ConfirmationPriority])

index¶

Unique payment identifier (<created_at_ms>-<payment_id>).

created_at_ms¶

When payment was created (ms since UNIX epoch).

updated_at_ms¶

When payment was last updated (ms since UNIX epoch).

rail¶

Technical rail used to fulfill this payment.

kind¶

Application-level payment kind.

direction¶

Payment direction (inbound, outbound, or info).

status¶

Payment status.

status_msg¶

Human-readable payment status message.

amount_sats¶

Payment amount in satoshis, if known.

fees_sats¶

Fees paid in satoshis.

note¶

Optional personal note attached to this payment.

invoice¶

BOLT11 invoice used for this payment, if any.

txid¶

Hex-encoded Bitcoin txid (on-chain payments only).

address¶

Bitcoin address for on-chain sends.

expires_at_ms¶

Invoice/offer expiry time (ms since UNIX epoch).

finalized_at_ms¶

When this payment finalized (ms since UNIX epoch).

payer_name¶

Payer’s self-reported name (offer payments).

payer_note¶

Payer’s provided note (offer payments).

priority¶

Confirmation priority for on-chain sends.

class lexe.Invoice(*, string, description, created_at_ms, expires_at_ms, amount_sats, payee_pubkey)¶

A BOLT11 Lightning invoice.

Parameters:

• string (str)

• description (Optional[str])

• created_at_ms (int)

• expires_at_ms (int)

• amount_sats (Optional[int])

• payee_pubkey (str)

string¶

Full bech32-encoded invoice string.

description¶

Invoice description, if present.

created_at_ms¶

Creation timestamp (ms since UNIX epoch).

expires_at_ms¶

Expiration timestamp (ms since UNIX epoch).

amount_sats¶

Amount in satoshis, if specified.

payee_pubkey¶

Hex-encoded payee node public key.

class lexe.PaymentSyncSummary(*, num_new, num_updated)¶

Summary of a payment sync operation.

Parameters:

• num_new (int)

• num_updated (int)

num_new¶

Number of new payments added to the local DB.

num_updated¶

Number of existing payments that were updated.

class lexe.ListPaymentsResponse(*, payments, next_index)¶

Response from listing payments.

Parameters:

• payments (List[Payment])

• next_index (Optional[str])

payments¶

Payments in the requested page.

next_index¶

Cursor for fetching the next page, or None if there are no more results.

class lexe.CreateInvoiceResponse(*, index, invoice, description, amount_sats, created_at_ms, expires_at_ms, payment_hash, payment_secret)¶

Response from creating a Lightning invoice.

Parameters:

• index (str)

• invoice (str)

• description (Optional[str])

• amount_sats (Optional[int])

• created_at_ms (int)

• expires_at_ms (int)

• payment_hash (str)

• payment_secret (str)

index¶

Unique payment identifier for this invoice.

invoice¶

BOLT11 invoice string.

description¶

Description encoded in the invoice, if provided.

amount_sats¶

Amount in satoshis, if specified.

created_at_ms¶

Invoice creation time (ms since UNIX epoch).

expires_at_ms¶

Invoice expiration time (ms since UNIX epoch).

payment_hash¶

Hex-encoded payment hash.

payment_secret¶

Payment secret.

class lexe.PayInvoiceResponse(*, index, created_at_ms)¶

Response from paying a Lightning invoice.

Parameters:

• index (str)

• created_at_ms (int)

index¶

Unique payment identifier for this payment.

created_at_ms¶

When payment was initiated (ms since UNIX epoch).

Functions¶

lexe.default_lexe_data_dir()¶

Returns the default Lexe data directory (~/.lexe).

Returns:

The absolute path to the default data directory.

Raises:

FfiError – If the home directory cannot be determined.

Return type:

str

Example:

data_dir = default_lexe_data_dir()
# '/home/user/.lexe'

lexe.init_logger(default_level='info')¶

Initialize the Lexe logger with the given default log level.

Call once at startup to enable logging.

Parameters:

default_level (str) – Log level string. One of "trace", "debug", "info", "warn", "error". Defaults to "info".

Return type:

None

Example:

init_logger()

Errors¶

class lexe.SeedFileError¶

Error type for seedphrase file operations.

Raised by RootSeed() file I/O methods (read(), read_from_path(), write(), write_to_path()).

Variants:

• NotFound – Seedphrase file not found. Attributes: path.

• ParseError – Failed to parse the seedphrase. Attributes: message.

• AlreadyExists – Seedphrase file already exists. Attributes: path.

• IoError – I/O error during the file operation. Attributes: message.

Example:

try:
    seed = RootSeed.read_from_path(path)
except SeedFileError.NotFound as e:
    print(f"No seed at {e.path}")
except SeedFileError.ParseError as e:
    print(f"Bad seed: {e.message}")

exception NotFound(path)¶

The seedphrase file was not found at the given path.

exception ParseError(message)¶

The seedphrase file could not be parsed (e.g. invalid mnemonic).

exception AlreadyExists(path)¶

A seedphrase file already exists at the given path.

exception IoError(message)¶

An I/O error occurred during the file operation.

class lexe.LoadWalletError¶

Error type for wallet loading operations.

Raised by LexeWallet.load() and AsyncLexeWallet.load().

Variants:

• NotFound – No local wallet data found for this user/environment.

• LoadFailed – Failed to load the wallet. Attributes: message.

Example:

try:
    wallet = LexeWallet.load(config, creds)
except LoadWalletError.NotFound:
    wallet = LexeWallet.fresh(config, creds)
except LoadWalletError.LoadFailed as e:
    print(f"Load failed: {e.message}")

exception NotFound¶

No local wallet data exists for this user and environment.

exception LoadFailed(message)¶

Failed to load the wallet (e.g. corrupted data, invalid seed).

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

Error type raised by SDK methods.

Catch this to handle Lexe SDK errors.

message()¶

Returns the error message string.

Return type:

str

Example:

try:
    info = wallet.node_info()
except FfiError as e:
    print(f"SDK error: {e.message()}")

message()¶

Returns the error message string.

Returns:

A human-readable description of the error.

Return type:

str