Lexe Python SDK¶

Configuration¶

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

Configuration for a wallet environment.

Use the factory constructors to create configs for standard environments.

Example:

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

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

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

classmethod mainnet()¶

Create config for Bitcoin mainnet.

Return type:: WalletEnvConfig

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

Create config for local development (regtest).

Parameters:

use_sgx (bool)
gateway_url (object | str | None)

Return type:

WalletEnvConfig

classmethod testnet3()¶

Create config for Bitcoin testnet3.

Return type:: WalletEnvConfig

deploy_env()¶

Get the configured deployment environment.

Return type:: DeployEnv

gateway_url()¶

Get the gateway URL for this environment. For dev, returns the configured override if present. For staging/prod, returns the canonical deploy-environment URL.

Return type:: str | None

network()¶

Get the configured Bitcoin network.

Return type:: LxNetwork

use_sgx()¶

Whether SGX is enabled for this config.

Return type:: bool

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.LxNetwork(*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(*, seed_bytes)¶

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

Parameters:: seed_bytes (bytes)

seed_bytes¶: 32-byte root seed.

class lexe.ClientCredentials(*, credentials_base64)¶

Client credentials for authenticating with Lexe.

Parameters:: credentials_base64 (str)

credentials_base64¶: Base64-encoded credentials blob.

Wallet¶

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

The main wallet handle for interacting with a Lexe Lightning node.

Create a wallet using the factory constructors, then call signup() and provision() before using payment methods.

Example:

config = WalletEnvConfig.mainnet()
seed = read_seed(config)

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

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

classmethod fresh(env_config, root_seed, 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 (WalletEnvConfig) – Wallet environment configuration.
root_seed (RootSeed) – The user’s root seed.
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

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

Load an existing wallet, or create a fresh one if none exists.

This is the recommended constructor for most use cases.

Parameters:

env_config (WalletEnvConfig) – Wallet environment configuration.
root_seed (RootSeed) – The user’s root seed.
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

async create_invoice(expiration_secs, amount_sats, description)¶

Create a BOLT11 Lightning invoice.

Parameters:

expiration_secs (int) – Invoice expiry in seconds (e.g. 3600 for 1 hour).
amount_sats (int | None) – Amount in satoshis, or None for an amountless invoice.
description (str | None) – Optional description shown to the payer.

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

delete_local_payments()¶

Delete 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 get_payment(payment_index)¶

Get a specific payment by its index.

Parameters:: payment_index (str) – Full 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

latest_payment_sync_index()¶

Get the latest payment sync watermark.

Returns:: The updated_at index of the most recently synced payment, or None if no payments have been synced yet.
Return type:: str | None

list_payments(filter, offset, limit)¶

List payments from local storage.

Reads from the local database only (no network calls). Call sync_payments() first to ensure data is fresh.

Parameters:

filter (PaymentFilter) – Which payments to include (PaymentFilter.ALL, PaymentFilter.PENDING, or PaymentFilter.FINALIZED).
offset (int) – Pagination offset (0-based).
limit (int) – Maximum number of payments to return.

Returns:

A ListPaymentsResponse with payments and total count.

Return type:

ListPaymentsResponse

Example:

await wallet.sync_payments()
resp = wallet.list_payments(PaymentFilter.ALL, offset=0, limit=20)
for p in resp.payments:
    print(f"{p.payment_index}: {p.amount_sats} sats ({p.status})")

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

Pay a BOLT11 Lightning invoice.

Parameters:

invoice (str) – BOLT11 invoice string to pay.
fallback_amount_sats (int | None) – Required if the invoice has no amount encoded.
note (str | None) – Optional private note (not visible to the receiver).

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_completion(
    resp.payment_index, timeout_secs=120,
)
print(f"Payment {payment.status}")

async provision(root_seed)¶

Ensure 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:: root_seed (RootSeed) – The user’s root seed.
Raises:: FfiError – If provisioning fails.
Return type:: None

Example:

wallet = LexeWallet.load_or_fresh(config, seed)
await wallet.provision(seed)

async signup(root_seed, partner_pk)¶

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 (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)
write_seed(seed, 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(payment_index, note)¶

Update a payment’s personal note.

Call sync_payments() first so the payment exists locally.

Parameters:

payment_index (str) – Full payment index string.
note (str | None) – New note text, or None to clear.

Raises:

FfiError – If the payment doesn’t exist locally.

Return type:

None

user_pk()¶

Get the user’s hex-encoded ed25519 public key.

Returns:: Hex string of the user’s public key derived from their root seed.
Return type:: str

async wait_for_payment_completion(payment_index, timeout_secs)¶

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.

Parameters:

payment_index (str) – Full payment index string.
timeout_secs (int) – Maximum wait time in seconds (recommended: 120, max: 10800 i.e. 3 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_completion(
    resp.payment_index, timeout_secs=120,
)
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(*, payment_index, payment_id, 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:

payment_index (str)
payment_id (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])

payment_index¶: Full payment index (<created_at_ms>-<payment_id>).

payment_id¶: Payment identifier without the timestamp.

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, total_count)¶

Response from listing payments.

Parameters:

payments (List[Payment])
total_count (int)

payments¶: Payments in the requested window.

total_count¶: Total number of payments for this filter.

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

Response from creating a Lightning invoice.

Parameters:

payment_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)

payment_index¶: Payment created index 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(*, payment_index, created_at_ms)¶

Response from paying a Lightning invoice.

Parameters:

payment_index (str)
created_at_ms (int)

payment_index¶: Payment created index for this payment.

created_at_ms¶: When payment was initiated (ms since UNIX epoch).

Payment Enums¶

class lexe.PaymentDirection(*values)¶

Direction of a payment relative to this wallet.

INBOUND – Incoming payment (receiving funds).
OUTBOUND – Outgoing payment (sending funds).
INFO – Informational (e.g. channel open/close events).

INBOUND = 0¶: Incoming payment.

OUTBOUND = 1¶: Outgoing payment.

INFO = 2¶: Informational payment.

class lexe.PaymentStatus(*values)¶

Status of a payment.

PENDING – Payment is in progress.
COMPLETED – Payment completed successfully.
FAILED – Payment failed.

PENDING = 0¶: Payment is pending.

COMPLETED = 1¶: Payment completed successfully.

FAILED = 2¶: Payment failed.

class lexe.PaymentFilter(*values)¶

Filter for listing payments from local storage.

ALL – Include all payments.
PENDING – Only pending payments.
FINALIZED – Only finalized payments (completed or failed).

ALL = 0¶: Include all payments.

PENDING = 1¶: Include only pending payments.

FINALIZED = 2¶: Include only finalized payments (completed or failed).

class lexe.PaymentKind¶

Application-level kind for a payment.

ONCHAIN – On-chain Bitcoin payment.
INVOICE – Lightning BOLT11 invoice payment.
OFFER – Lightning BOLT12 offer payment.
SPONTANEOUS – Spontaneous (keysend) Lightning payment.
WAIVED_CHANNEL_FEE – Waived channel fee.
WAIVED_LIQUIDITY_FEE – Waived liquidity fee.
UNKNOWN – Unknown kind from a newer node version.

ONCHAIN¶: alias of ONCHAIN

INVOICE¶: alias of INVOICE

OFFER¶: alias of OFFER

SPONTANEOUS¶: alias of SPONTANEOUS

WAIVED_CHANNEL_FEE¶: alias of WAIVED_CHANNEL_FEE

WAIVED_LIQUIDITY_FEE¶: alias of WAIVED_LIQUIDITY_FEE

UNKNOWN¶: alias of UNKNOWN

class lexe.PaymentRail(*values)¶

Technical rail used to fulfill a payment.

ONCHAIN – On-chain Bitcoin transaction.
INVOICE – Lightning BOLT11 invoice.
OFFER – Lightning BOLT12 offer.
SPONTANEOUS – Spontaneous (keysend) Lightning payment.
WAIVED_FEE – Internal waived fee.
UNKNOWN – Unknown rail from a newer node version.

ONCHAIN = 0¶: On-chain Bitcoin payment.

INVOICE = 1¶: Lightning invoice payment.

OFFER = 2¶: Lightning offer payment.

SPONTANEOUS = 3¶: Spontaneous Lightning payment.

WAIVED_FEE = 4¶: Waived fee payment.

UNKNOWN = 5¶: Unknown rail from a newer version of node.

class lexe.ConfirmationPriority(*values)¶

Confirmation priority for on-chain Bitcoin transactions.

HIGH – Fastest confirmation (highest fees).
NORMAL – Standard confirmation target.
BACKGROUND – Lowest fees (slowest confirmation).

HIGH = 0¶: Fastest confirmation (highest fees).

NORMAL = 1¶: Standard confirmation target.

BACKGROUND = 2¶: Lowest fees (slowest confirmation).

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.seedphrase_path(env_config, lexe_data_dir)¶

Returns the path to the seedphrase file for the given environment.

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

Parameters:

env_config (WalletEnvConfig) – Wallet environment configuration.
lexe_data_dir (str) – Base data directory path.

Returns:

The absolute path to the seedphrase file.

Return type:

str

Example:

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

lexe.read_seed(env_config)¶

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

Parameters:: env_config (WalletEnvConfig) – Wallet environment configuration.
Returns:: The root seed, or None if the file doesn’t exist.
Raises:: FfiError – If the file exists but cannot be read or parsed.
Return type:: RootSeed | None

Example:

config = WalletEnvConfig.mainnet()
seed = read_seed(config)
if seed is not None:
    print(f"Loaded seed ({len(seed.seed_bytes)} bytes)")

lexe.read_seed_from_path(path)¶

Reads a root seed from a seedphrase file at the given path.

The file should contain a BIP39 mnemonic phrase.

Parameters:: path (str) – Absolute path to the seedphrase file.
Returns:: The root seed, or None if the file doesn’t exist.
Raises:: FfiError – If the file exists but cannot be read or parsed.
Return type:: RootSeed | None

lexe.write_seed(root_seed, env_config)¶

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

Creates parent directories if needed.

Parameters:

root_seed (RootSeed) – The root seed to persist.
env_config (WalletEnvConfig) – Wallet environment configuration.

Raises:

FfiError – If the file already exists or cannot be written.

Return type:

None

lexe.write_seed_to_path(root_seed, path)¶

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

Creates parent directories if needed.

Parameters:

root_seed (RootSeed) – The root seed to persist.
path (str) – Absolute path to write the seedphrase file.

Raises:

FfiError – If the file already exists or cannot be written.

Return type:

None

lexe.init_logger(default_level)¶

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".
Return type:: None

Example:

init_logger("info")

lexe.try_load_wallet(env_config, root_seed, lexe_data_dir=<object object>)¶

Try to load an existing wallet from local state.

Returns None if no local data exists for this user/environment. If this returns None, use LexeWallet.fresh() to create local state.

It is recommended to always pass the same lexe_data_dir, regardless of environment or user. Data is namespaced internally.

Parameters:

env_config (WalletEnvConfig) – Wallet environment configuration.
root_seed (RootSeed) – The user’s root seed.
lexe_data_dir (object | str | None) – Base data directory (default: ~/.lexe).

Returns:

The loaded wallet, or None if no local data exists.

Raises:

FfiError – If local data exists but is corrupted.

Return type:

LexeWallet | None

Example:

config = WalletEnvConfig.mainnet()
wallet = try_load_wallet(config, seed)
if wallet is None:
    wallet = LexeWallet.fresh(config, seed)

Errors¶

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

Error type raised by SDK methods.

Catch this to handle Lexe SDK errors.

Example:

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

message()¶

Get the error message.

Return type:: str