lnbot

package module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 5, 2026 License: MIT Imports: 11 Imported by: 1

README

ln.bot-go

Go Reference

The official Go SDK for ln.bot — Bitcoin for AI Agents.

Give your AI agents, apps, and services access to Bitcoin over the Lightning Network. Create wallets, send and receive sats, and get real-time payment notifications.

client := lnbot.New("uk_...")
w := client.Wallet("wal_...")

invoice, _ := w.Invoices.Create(ctx, &lnbot.CreateInvoiceParams{
    Amount: 1000,
    Memo:   lnbot.Ptr("Coffee"),
})

ln.bot also ships a TypeScript SDK, Python SDK, Rust SDK, CLI, and MCP server.

Install

go get github.com/lnbotdev/go-sdk

Quick start

Register an account
package main

import (
    "context"
    "fmt"

    lnbot "github.com/lnbotdev/go-sdk"
)

func main() {
    ctx := context.Background()

    // Register (no auth needed)
    client := lnbot.New("")
    account, _ := client.Register(ctx)
    fmt.Println("User key:", account.PrimaryKey)
    fmt.Println("Recovery:", account.RecoveryPassphrase)

    // Create a wallet
    authed := lnbot.New(account.PrimaryKey)
    wallet, _ := authed.Wallets.Create(ctx)
    fmt.Println("Wallet:", wallet.WalletID)
    fmt.Println("Address:", wallet.Address)
}
Receive sats
client := lnbot.New("uk_...")
w := client.Wallet("wal_...")

invoice, _ := w.Invoices.Create(ctx, &lnbot.CreateInvoiceParams{
    Amount: 1000,
    Memo:   lnbot.Ptr("Payment for task #42"),
})
fmt.Println(invoice.Bolt11)
Wait for payment (SSE)

SSE streams require a wallet key (wk_):

// Create a wallet key (one-time setup)
wk, _ := w.Key.Create(ctx)

// Use the wallet key client for SSE
wkClient := lnbot.New(wk.Key)
events, errs := wkClient.Wallet("wal_...").Invoices.Watch(ctx, invoice.Number, nil)
for event := range events {
    if event.Event == "settled" {
        fmt.Println("Paid!")
    }
}
if err := <-errs; err != nil {
    log.Fatal(err)
}
Send sats
payment, _ := w.Payments.Create(ctx, &lnbot.CreatePaymentParams{
    Target: "alice@ln.bot",
    Amount: lnbot.Ptr(int64(500)),
})
Resolve before sending
res, _ := w.Payments.Resolve(ctx, "alice@ln.bot")
fmt.Printf("type=%s min=%d max=%d\n", res.Type, *res.Min, *res.Max)
Check balance
wal, _ := w.Get(ctx)
fmt.Printf("%d sats available\n", wal.Available)
List wallets
wallets, _ := client.Wallets.List(ctx)
for _, w := range wallets {
    fmt.Printf("%s — %s\n", w.WalletID, w.Name)
}

Authentication

ln.bot uses two key types:

Key type Prefix Scope Created by
User key uk_ All wallets under the account Register()
Wallet key wk_ Single wallet only wallet.Key.Create()

Use user keys for most operations. Use wallet keys for SSE streams or to give scoped access to a single wallet.

L402 paywalls

w := client.Wallet("wal_...")

// Create a challenge (server side)
challenge, _ := w.L402.CreateChallenge(ctx, &lnbot.CreateL402ChallengeParams{
    Amount:      100,
    Description: lnbot.Ptr("API access"),
})

// Pay the challenge (client side)
result, _ := w.L402.Pay(ctx, &lnbot.PayL402Params{
    WwwAuthenticate: challenge.WwwAuthenticate,
})

// Verify a token (server side, stateless)
v, _ := w.L402.Verify(ctx, &lnbot.VerifyL402Params{
    Authorization: *result.Authorization,
})
fmt.Println(v.Valid)

Error handling

import "errors"

wal, err := client.Wallet("wal_...").Get(ctx)
if err != nil {
    // Match any API error
    var apiErr *lnbot.APIError
    if errors.As(err, &apiErr) {
        fmt.Println(apiErr.StatusCode, apiErr.Message)
    }

    // Match specific error types
    var notFound *lnbot.NotFoundError
    var badReq *lnbot.BadRequestError
    var conflict *lnbot.ConflictError

    switch {
    case errors.As(err, &notFound):
        // 404
    case errors.As(err, &badReq):
        // 400
    case errors.As(err, &conflict):
        // 409
    default:
        // other error
    }
}

Configuration

client := lnbot.New("uk_...",
    lnbot.WithBaseURL("https://api.ln.bot"),
    lnbot.WithHTTPClient(customHTTPClient),
)

API reference

Client (top-level)
Method Description
Register(ctx) Create a new account (no auth)
Me(ctx) Get authenticated identity
Wallet(id) Get a wallet handle
Wallets.Create(ctx) Create a new wallet
Wallets.List(ctx) List all wallets
Keys.Rotate(ctx, slot) Rotate user key (0=primary, 1=secondary)
Invoices.CreateForWallet(ctx, params) Public invoice by wallet ID
Invoices.CreateForAddress(ctx, params) Public invoice by Lightning address
Backup.Recovery(ctx) Get recovery passphrase
Backup.PasskeyBegin(ctx) Start passkey registration
Backup.PasskeyComplete(ctx, params) Complete passkey registration
Restore.Recovery(ctx, params) Restore via passphrase
Restore.PasskeyBegin(ctx) Start passkey auth
Restore.PasskeyComplete(ctx, params) Complete passkey restore
Wallet handle
Method Description
Get(ctx) Get wallet details
Update(ctx, params) Update wallet (rename)
Key.Create(ctx) Create wallet key (max 1)
Key.Get(ctx) Get wallet key info
Key.Delete(ctx) Revoke wallet key
Key.Rotate(ctx) Rotate wallet key
Invoices.Create(ctx, params) Create invoice
Invoices.List(ctx, params) List invoices
Invoices.Get(ctx, number) Get invoice by number
Invoices.Watch(ctx, number, timeout) SSE stream (requires wk_)
Payments.Create(ctx, params) Send payment
Payments.List(ctx, params) List payments
Payments.Get(ctx, number) Get payment by number
Payments.Resolve(ctx, target) Inspect target before paying
Payments.Watch(ctx, number, timeout) SSE stream (requires wk_)
Addresses.Create(ctx, params) Create Lightning address
Addresses.List(ctx) List addresses
Addresses.Delete(ctx, address) Delete address
Addresses.Transfer(ctx, address, params) Transfer address
Transactions.List(ctx, params) List transactions
Webhooks.Create(ctx, params) Register webhook
Webhooks.List(ctx) List webhooks
Webhooks.Delete(ctx, id) Delete webhook
Events.Stream(ctx) SSE stream (requires wk_)
L402.CreateChallenge(ctx, params) Create L402 challenge
L402.Verify(ctx, params) Verify L402 token
L402.Pay(ctx, params) Pay L402 challenge

Features

  • Zero dependencies — stdlib net/http + encoding/json only
  • Context-first — every method takes context.Context as the first argument
  • Wallet-scoped — client.Wallet(id) returns a handle with all sub-resources
  • Typed errors — BadRequestError, NotFoundError, ConflictError, UnauthorizedError, ForbiddenError
  • Generic helpers — Ptr[T] for optional fields
  • SSE support — Watch returns channels for real-time events

Requirements

  • Go 1.21+
  • Get your API key at ln.bot

Other SDKs

License

MIT

Documentation

Overview

Package lnbot is the official Go SDK for ln.bot — Bitcoin for AI Agents.

Send and receive sats over the Lightning Network. Create wallets, generate invoices, make payments, and stream real-time settlement events via SSE.

Zero dependencies beyond the standard library. Every method takes a context.Context as its first argument. 

client := lnbot.New("uk_...")
w := client.Wallet("wal_...")
invoice, _ := w.Invoices.Create(ctx, &lnbot.CreateInvoiceParams{
    Amount: 1000,
    Memo:   lnbot.Ptr("Coffee"),
})

Get your API key at https://ln.bot

Also available as a TypeScript SDK (https://www.npmjs.com/package/@lnbot/sdk), Python SDK (https://pypi.org/project/lnbot/), and Rust SDK (https://crates.io/crates/lnbot).

Index

Constants

View Source 
const (

	// Version is the SDK version sent in the User-Agent header.
	Version = "1.0.0"
)

Variables

This section is empty.

Functions

func Ptr 

func Ptr[T any](v T) *T

Ptr returns a pointer to v. Useful for optional fields in request params.

Types

type APIError 

type APIError struct {
	StatusCode int
	Message    string
	Body       string
}

APIError represents an error response from the LnBot API.

func (*APIError) Error 

func (e *APIError) Error() string

type Address 

type Address struct {
	Address   string     `json:"address"`
	Generated bool       `json:"generated"`
	Cost      int64      `json:"cost"`
	CreatedAt *time.Time `json:"createdAt"`
}

Address represents a Lightning address.

type AddressInvoice added in v0.3.0 

type AddressInvoice struct {
	Bolt11    string     `json:"bolt11"`
	Amount    int64      `json:"amount"`
	ExpiresAt *time.Time `json:"expiresAt"`
}

AddressInvoice is an invoice created via wallet ID or Lightning address.

type AddressTransfer 

type AddressTransfer struct {
	Address       string `json:"address"`
	TransferredTo string `json:"transferredTo"`
}

AddressTransfer is returned after transferring an address.

type AddressesService 

type AddressesService struct {
	// contains filtered or unexported fields
}

AddressesService handles wallet-scoped Lightning address operations.

func (*AddressesService) Create 

func (s *AddressesService) Create(ctx context.Context, params *CreateAddressParams) (*Address, error)

Create creates a new Lightning address for the wallet.

func (*AddressesService) Delete 

func (s *AddressesService) Delete(ctx context.Context, address string) error

Delete removes a Lightning address.

func (*AddressesService) List 

func (s *AddressesService) List(ctx context.Context) ([]Address, error)

List returns all Lightning addresses for the wallet.

func (*AddressesService) Transfer 

func (s *AddressesService) Transfer(ctx context.Context, address string, params *TransferAddressParams) (*AddressTransfer, error)

Transfer moves a Lightning address to another wallet.

type BackupService 

type BackupService struct {
	// contains filtered or unexported fields
}

BackupService handles wallet backup operations.

func (*BackupService) PasskeyBegin 

func (s *BackupService) PasskeyBegin(ctx context.Context) (*PasskeyRegistrationChallenge, error)

PasskeyBegin starts the passkey registration flow for wallet backup.

func (*BackupService) PasskeyComplete 

func (s *BackupService) PasskeyComplete(ctx context.Context, params *PasskeyAttestationParams) error

PasskeyComplete finishes the passkey registration flow by verifying the attestation.

func (*BackupService) Recovery 

func (s *BackupService) Recovery(ctx context.Context) (*RecoveryPassphrase, error)

Recovery generates a recovery passphrase for the current wallet.

type BadRequestError 

type BadRequestError struct{ *APIError }

BadRequestError is returned for 400 responses.

func (*BadRequestError) Unwrap 

func (e *BadRequestError) Unwrap() error

type Client 

type Client struct {

	// Top-level (account) services
	Wallets  *WalletsService
	Keys     *KeysService
	Invoices *PublicInvoicesService
	Backup   *BackupService
	Restore  *RestoreService
	// contains filtered or unexported fields
}

Client is the LnBot API client.

func New 

func New(apiKey string, opts ...Option) *Client

New creates a new LnBot client. Pass an empty string for apiKey if not needed (registration, public invoices, restore).

func (*Client) Me added in v1.0.0 

func (c *Client) Me(ctx context.Context) (*MeResponse, error)

Me returns the authenticated identity.

func (*Client) Register added in v1.0.0 

func (c *Client) Register(ctx context.Context) (*RegisterResponse, error)

Register creates a new account. No authentication required.

func (*Client) Wallet added in v1.0.0 

func (c *Client) Wallet(id string) *WalletHandle

Wallet returns a wallet handle scoped to the given wallet ID. All sub-resources (invoices, payments, addresses, etc.) are accessed through this handle.

type ConflictError 

type ConflictError struct{ *APIError }

ConflictError is returned for 409 responses.

func (*ConflictError) Unwrap 

func (e *ConflictError) Unwrap() error

type CreateAddressParams 

type CreateAddressParams struct {
	Address *string `json:"address,omitempty"`
}

CreateAddressParams are the parameters for creating a Lightning address.

type CreateInvoiceForAddressParams added in v0.3.0 

type CreateInvoiceForAddressParams struct {
	Address string  `json:"address"`
	Amount  int64   `json:"amount"`
	Tag     *string `json:"tag,omitempty"`
	Comment *string `json:"comment,omitempty"`
}

CreateInvoiceForAddressParams are the parameters for creating an invoice for a Lightning address. No authentication required. Rate limited by IP.

type CreateInvoiceForWalletParams added in v0.3.0 

type CreateInvoiceForWalletParams struct {
	WalletID  string  `json:"walletId"`
	Amount    int64   `json:"amount"`
	Reference *string `json:"reference,omitempty"`
	Comment   *string `json:"comment,omitempty"`
}

CreateInvoiceForWalletParams are the parameters for creating an invoice for a specific wallet. No authentication required. Rate limited by IP.

type CreateInvoiceParams 

type CreateInvoiceParams struct {
	Amount    int64   `json:"amount"`
	Reference *string `json:"reference,omitempty"`
	Memo      *string `json:"memo,omitempty"`
}

CreateInvoiceParams are the parameters for creating a new invoice.

type CreateL402ChallengeParams added in v0.5.0 

type CreateL402ChallengeParams struct {
	Amount        int64    `json:"amount"`
	Description   *string  `json:"description,omitempty"`
	ExpirySeconds *int     `json:"expirySeconds,omitempty"`
	Caveats       []string `json:"caveats,omitempty"`
}

CreateL402ChallengeParams are the parameters for creating an L402 challenge.

type CreatePaymentParams 

type CreatePaymentParams struct {
	Target         string  `json:"target"`
	Amount         *int64  `json:"amount,omitempty"`
	IdempotencyKey *string `json:"idempotencyKey,omitempty"`
	MaxFee         *int64  `json:"maxFee,omitempty"`
	Reference      *string `json:"reference,omitempty"`
}

CreatePaymentParams are the parameters for creating a new payment. Target accepts a Lightning address (user@domain), LNURL, or BOLT11 invoice.

type CreateWalletResponse added in v1.0.0 

type CreateWalletResponse struct {
	WalletID string `json:"walletId"`
	Name     string `json:"name"`
	Address  string `json:"address"`
}

CreateWalletResponse is returned when a new wallet is created.

type CreateWebhookParams 

type CreateWebhookParams struct {
	URL string `json:"url"`
}

CreateWebhookParams are the parameters for creating a webhook.

type EventsService added in v0.4.0 

type EventsService struct {
	// contains filtered or unexported fields
}

EventsService handles the wallet-scoped event stream.

func (*EventsService) Stream added in v0.4.0 

func (s *EventsService) Stream(ctx context.Context) (<-chan WalletEvent, <-chan error)

Stream opens an SSE stream of all wallet events. Events include invoice.created, invoice.settled, payment.created, payment.settled, and payment.failed. The channel is closed when the stream ends. Cancel the context to abort.

type ForbiddenError 

type ForbiddenError struct{ *APIError }

ForbiddenError is returned for 403 responses.

func (*ForbiddenError) Unwrap 

func (e *ForbiddenError) Unwrap() error

type Invoice 

type Invoice struct {
	Number    int        `json:"number"`
	Status    string     `json:"status"`
	Amount    int64      `json:"amount"`
	Bolt11    string     `json:"bolt11"`
	Reference *string    `json:"reference"`
	Memo      *string    `json:"memo"`
	Preimage  *string    `json:"preimage"`
	TxNumber  *int       `json:"txNumber"`
	CreatedAt *time.Time `json:"createdAt"`
	SettledAt *time.Time `json:"settledAt"`
	ExpiresAt *time.Time `json:"expiresAt"`
}

Invoice represents a Lightning invoice.

type InvoiceEvent 

type InvoiceEvent struct {
	Event string
	Data  Invoice
}

InvoiceEvent represents a server-sent event for an invoice.

type InvoicesService 

type InvoicesService struct {
	// contains filtered or unexported fields
}

InvoicesService handles wallet-scoped Lightning invoice operations.

func (*InvoicesService) Create 

func (s *InvoicesService) Create(ctx context.Context, params *CreateInvoiceParams) (*Invoice, error)

Create creates a new Lightning invoice.

func (*InvoicesService) Get 

func (s *InvoicesService) Get(ctx context.Context, number int) (*Invoice, error)

Get returns a single invoice by number.

func (*InvoicesService) GetByHash added in v0.5.0 

func (s *InvoicesService) GetByHash(ctx context.Context, paymentHash string) (*Invoice, error)

GetByHash returns a single invoice by its payment hash.

func (*InvoicesService) List 

func (s *InvoicesService) List(ctx context.Context, params *ListInvoicesParams) ([]Invoice, error)

List returns invoices for the wallet.

func (*InvoicesService) Watch 

func (s *InvoicesService) Watch(ctx context.Context, number int, timeout *int) (<-chan InvoiceEvent, <-chan error)

Watch opens an SSE stream and sends events to the returned channel. The channel is closed when the stream ends. Cancel the context to abort.

func (*InvoicesService) WatchByHash added in v0.5.0 

func (s *InvoicesService) WatchByHash(ctx context.Context, paymentHash string, timeout *int) (<-chan InvoiceEvent, <-chan error)

WatchByHash opens an SSE stream for an invoice identified by payment hash.

type KeysService 

type KeysService struct {
	// contains filtered or unexported fields
}

KeysService handles API key operations.

func (*KeysService) Rotate 

func (s *KeysService) Rotate(ctx context.Context, slot int) (*RotatedAPIKey, error)

Rotate rotates the API key at the given slot (0 = primary, 1 = secondary).

type L402Challenge added in v0.5.0 

type L402Challenge struct {
	Macaroon        string    `json:"macaroon"`
	Invoice         string    `json:"invoice"`
	PaymentHash     string    `json:"paymentHash"`
	ExpiresAt       time.Time `json:"expiresAt"`
	WwwAuthenticate string    `json:"wwwAuthenticate"`
}

L402Challenge is returned when an L402 challenge is created.

type L402PayResponse added in v0.5.0 

type L402PayResponse struct {
	Authorization *string `json:"authorization"`
	PaymentHash   string  `json:"paymentHash"`
	Preimage      *string `json:"preimage"`
	Amount        int64   `json:"amount"`
	Fee           *int64  `json:"fee"`
	PaymentNumber int     `json:"paymentNumber"`
	Status        string  `json:"status"`
}

L402PayResponse is returned after paying an L402 challenge.

type L402Service added in v0.5.0 

type L402Service struct {
	// contains filtered or unexported fields
}

L402Service handles wallet-scoped L402 paywall authentication operations.

func (*L402Service) CreateChallenge added in v0.5.0 

func (s *L402Service) CreateChallenge(ctx context.Context, params *CreateL402ChallengeParams) (*L402Challenge, error)

CreateChallenge creates an L402 challenge (invoice + macaroon) for paywall authentication.

func (*L402Service) Pay added in v0.5.0 

func (s *L402Service) Pay(ctx context.Context, params *PayL402Params) (*L402PayResponse, error)

Pay pays an L402 challenge and returns a ready-to-use Authorization header.

func (*L402Service) Verify added in v0.5.0 

func (s *L402Service) Verify(ctx context.Context, params *VerifyL402Params) (*VerifyL402Response, error)

Verify verifies an L402 authorization token. Stateless — checks signature, preimage, and caveats.

type ListInvoicesParams 

type ListInvoicesParams struct {
	Limit *int
	After *int
}

ListInvoicesParams are the pagination parameters for listing invoices.

type ListPaymentsParams 

type ListPaymentsParams struct {
	Limit *int
	After *int
}

ListPaymentsParams are the pagination parameters for listing payments.

type ListTransactionsParams 

type ListTransactionsParams struct {
	Limit *int
	After *int
}

ListTransactionsParams are the pagination parameters for listing transactions.

type MeResponse added in v1.0.0 

type MeResponse struct {
	WalletID string `json:"walletId"`
}

MeResponse is returned by the identity check endpoint.

type NotFoundError 

type NotFoundError struct{ *APIError }

NotFoundError is returned for 404 responses.

func (*NotFoundError) Unwrap 

func (e *NotFoundError) Unwrap() error

type Option 

type Option func(*Client)

Option configures the Client.

func WithBaseURL 

func WithBaseURL(u string) Option

WithBaseURL sets a custom API base URL.

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient sets a custom *http.Client.

type PasskeyAssertionParams 

type PasskeyAssertionParams struct {
	SessionID string         `json:"sessionId"`
	Assertion map[string]any `json:"assertion"`
}

PasskeyAssertionParams are the parameters for completing passkey restore.

type PasskeyAttestationParams 

type PasskeyAttestationParams struct {
	SessionID   string         `json:"sessionId"`
	Attestation map[string]any `json:"attestation"`
}

PasskeyAttestationParams are the parameters for completing passkey backup.

type PasskeyAuthenticationChallenge 

type PasskeyAuthenticationChallenge struct {
	SessionID string         `json:"sessionId"`
	Options   map[string]any `json:"options"`
}

PasskeyAuthenticationChallenge is returned when beginning passkey restore.

type PasskeyRegistrationChallenge 

type PasskeyRegistrationChallenge struct {
	SessionID string         `json:"sessionId"`
	Options   map[string]any `json:"options"`
}

PasskeyRegistrationChallenge is returned when beginning passkey backup.

type PayL402Params added in v0.5.0 

type PayL402Params struct {
	WwwAuthenticate string  `json:"wwwAuthenticate"`
	MaxFee          *int64  `json:"maxFee,omitempty"`
	Reference       *string `json:"reference,omitempty"`
	Wait            *bool   `json:"wait,omitempty"`
	Timeout         *int    `json:"timeout,omitempty"`
}

PayL402Params are the parameters for paying an L402 challenge.

type Payment 

type Payment struct {
	Number        int        `json:"number"`
	Status        string     `json:"status"`
	Amount        int64      `json:"amount"`
	MaxFee        int64      `json:"maxFee"`
	ServiceFee    int64      `json:"serviceFee"`
	ActualFee     *int64     `json:"actualFee"`
	Address       string     `json:"address"`
	Reference     *string    `json:"reference"`
	Preimage      *string    `json:"preimage"`
	TxNumber      *int       `json:"txNumber"`
	FailureReason *string    `json:"failureReason"`
	CreatedAt     *time.Time `json:"createdAt"`
	SettledAt     *time.Time `json:"settledAt"`
}

Payment represents a Lightning payment.

type PaymentEvent added in v0.3.0 

type PaymentEvent struct {
	Event string
	Data  Payment
}

PaymentEvent represents a server-sent event for a payment.

type PaymentsService 

type PaymentsService struct {
	// contains filtered or unexported fields
}

PaymentsService handles wallet-scoped Lightning payment operations.

func (*PaymentsService) Create 

func (s *PaymentsService) Create(ctx context.Context, params *CreatePaymentParams) (*Payment, error)

Create sends a new Lightning payment.

func (*PaymentsService) Get 

func (s *PaymentsService) Get(ctx context.Context, number int) (*Payment, error)

Get returns a single payment by number.

func (*PaymentsService) GetByHash added in v0.5.0 

func (s *PaymentsService) GetByHash(ctx context.Context, paymentHash string) (*Payment, error)

GetByHash returns a single payment by its payment hash.

func (*PaymentsService) List 

func (s *PaymentsService) List(ctx context.Context, params *ListPaymentsParams) ([]Payment, error)

List returns payments for the wallet.

func (*PaymentsService) Resolve added in v1.0.0 

func (s *PaymentsService) Resolve(ctx context.Context, target string) (*ResolveTargetResponse, error)

Resolve inspects a payment target (Lightning address, LNURL, or BOLT11) before sending.

func (*PaymentsService) Watch added in v0.3.0 

func (s *PaymentsService) Watch(ctx context.Context, number int, timeout *int) (<-chan PaymentEvent, <-chan error)

Watch opens an SSE stream and sends events to the returned channel.

func (*PaymentsService) WatchByHash added in v0.5.0 

func (s *PaymentsService) WatchByHash(ctx context.Context, paymentHash string, timeout *int) (<-chan PaymentEvent, <-chan error)

WatchByHash opens an SSE stream for a payment identified by payment hash.

type PublicInvoicesService added in v1.0.0 

type PublicInvoicesService struct {
	// contains filtered or unexported fields
}

PublicInvoicesService handles public (no-auth) invoice creation.

func (*PublicInvoicesService) CreateForAddress added in v1.0.0 

func (s *PublicInvoicesService) CreateForAddress(ctx context.Context, params *CreateInvoiceForAddressParams) (*AddressInvoice, error)

CreateForAddress creates an invoice for the wallet owning the given Lightning address. No authentication required. Rate limited by IP.

func (*PublicInvoicesService) CreateForWallet added in v1.0.0 

func (s *PublicInvoicesService) CreateForWallet(ctx context.Context, params *CreateInvoiceForWalletParams) (*AddressInvoice, error)

CreateForWallet creates an invoice for a specific wallet by its ID (wal_xxx). No authentication required. Rate limited by IP.

type RecoveryPassphrase 

type RecoveryPassphrase struct {
	Passphrase string `json:"passphrase"`
}

RecoveryPassphrase is returned when backup via recovery passphrase is initiated.

type RecoveryRestoreParams 

type RecoveryRestoreParams struct {
	Passphrase string `json:"passphrase"`
}

RecoveryRestoreParams are the parameters for restoring via recovery passphrase.

type RegisterResponse added in v1.0.0 

type RegisterResponse struct {
	UserID             string `json:"userId"`
	PrimaryKey         string `json:"primaryKey"`
	SecondaryKey       string `json:"secondaryKey"`
	RecoveryPassphrase string `json:"recoveryPassphrase"`
}

RegisterResponse is returned when a new account is registered.

type ResolveTargetResponse added in v1.0.0 

type ResolveTargetResponse struct {
	Type   string `json:"type"`
	Min    *int64 `json:"min"`
	Max    *int64 `json:"max"`
	Fixed  *bool  `json:"fixed"`
	Amount *int64 `json:"amount"`
}

ResolveTargetResponse is returned when resolving a payment target.

type RestoreService 

type RestoreService struct {
	// contains filtered or unexported fields
}

RestoreService handles wallet restore operations.

func (*RestoreService) PasskeyBegin 

func (s *RestoreService) PasskeyBegin(ctx context.Context) (*PasskeyAuthenticationChallenge, error)

PasskeyBegin starts the passkey authentication flow for wallet restore.

func (*RestoreService) PasskeyComplete 

func (s *RestoreService) PasskeyComplete(ctx context.Context, params *PasskeyAssertionParams) (*RestoredWallet, error)

PasskeyComplete finishes the passkey authentication flow and restores the wallet.

func (*RestoreService) Recovery 

func (s *RestoreService) Recovery(ctx context.Context, params *RecoveryRestoreParams) (*RestoredWallet, error)

Recovery restores a wallet using a recovery passphrase. Does not require authentication.

type RestoredWallet 

type RestoredWallet struct {
	WalletID     string `json:"walletId"`
	Name         string `json:"name"`
	PrimaryKey   string `json:"primaryKey"`
	SecondaryKey string `json:"secondaryKey"`
}

RestoredWallet is returned after a successful wallet restore.

type RotatedAPIKey 

type RotatedAPIKey struct {
	Key  string `json:"key"`
	Name string `json:"name"`
}

RotatedAPIKey is returned after rotating an API key.

type Transaction 

type Transaction struct {
	Number       int        `json:"number"`
	Type         string     `json:"type"`
	Amount       int64      `json:"amount"`
	BalanceAfter int64      `json:"balanceAfter"`
	NetworkFee   int64      `json:"networkFee"`
	ServiceFee   int64      `json:"serviceFee"`
	PaymentHash  *string    `json:"paymentHash"`
	Preimage     *string    `json:"preimage"`
	Reference    *string    `json:"reference"`
	Note         *string    `json:"note"`
	CreatedAt    *time.Time `json:"createdAt"`
}

Transaction represents a wallet transaction.

type TransactionsService 

type TransactionsService struct {
	// contains filtered or unexported fields
}

TransactionsService handles wallet-scoped transaction operations.

func (*TransactionsService) List 

func (s *TransactionsService) List(ctx context.Context, params *ListTransactionsParams) ([]Transaction, error)

List returns transactions for the wallet.

type TransferAddressParams 

type TransferAddressParams struct {
	TargetWalletKey string `json:"targetWalletKey"`
}

TransferAddressParams are the parameters for transferring an address.

type UnauthorizedError 

type UnauthorizedError struct{ *APIError }

UnauthorizedError is returned for 401 responses.

func (*UnauthorizedError) Unwrap 

func (e *UnauthorizedError) Unwrap() error

type UpdateWalletParams 

type UpdateWalletParams struct {
	Name string `json:"name"`
}

UpdateWalletParams are the parameters for updating a wallet.

type VerifyL402Params added in v0.5.0 

type VerifyL402Params struct {
	Authorization string `json:"authorization"`
}

VerifyL402Params are the parameters for verifying an L402 token.

type VerifyL402Response added in v0.5.0 

type VerifyL402Response struct {
	Valid       bool     `json:"valid"`
	PaymentHash *string  `json:"paymentHash"`
	Caveats     []string `json:"caveats"`
	Error       *string  `json:"error"`
}

VerifyL402Response is returned when verifying an L402 token.

type Wallet 

type Wallet struct {
	WalletID  string `json:"walletId"`
	Name      string `json:"name"`
	Balance   int64  `json:"balance"`
	OnHold    int64  `json:"onHold"`
	Available int64  `json:"available"`
}

Wallet represents a LnBot wallet.

type WalletEvent added in v0.4.0 

type WalletEvent struct {
	Event     string          `json:"event"`
	CreatedAt string          `json:"createdAt"`
	Data      json.RawMessage `json:"data"`
}

WalletEvent represents a real-time event from the wallet event stream.

type WalletHandle added in v1.0.0 

type WalletHandle struct {
	WalletID string

	Key          *WalletKeyService
	Invoices     *InvoicesService
	Payments     *PaymentsService
	Addresses    *AddressesService
	Transactions *TransactionsService
	Webhooks     *WebhooksService
	Events       *EventsService
	L402         *L402Service
	// contains filtered or unexported fields
}

WalletHandle provides access to wallet-scoped resources.

func (*WalletHandle) Get added in v1.0.0 

func (w *WalletHandle) Get(ctx context.Context) (*Wallet, error)

Get returns the wallet details.

func (*WalletHandle) Update added in v1.0.0 

func (w *WalletHandle) Update(ctx context.Context, params *UpdateWalletParams) (*Wallet, error)

Update modifies the wallet's settings.

type WalletKeyInfoResponse added in v1.0.0 

type WalletKeyInfoResponse struct {
	Hint       string     `json:"hint"`
	CreatedAt  *time.Time `json:"createdAt"`
	LastUsedAt *time.Time `json:"lastUsedAt"`
}

WalletKeyInfoResponse is returned when getting wallet key info.

type WalletKeyResponse added in v1.0.0 

type WalletKeyResponse struct {
	Key  string `json:"key"`
	Hint string `json:"hint"`
}

WalletKeyResponse is returned when a wallet key is created or rotated.

type WalletKeyService added in v1.0.0 

type WalletKeyService struct {
	// contains filtered or unexported fields
}

WalletKeyService handles wallet key operations.

func (*WalletKeyService) Create added in v1.0.0 

func (s *WalletKeyService) Create(ctx context.Context) (*WalletKeyResponse, error)

Create creates a wallet key (max 1 per wallet).

func (*WalletKeyService) Delete added in v1.0.0 

func (s *WalletKeyService) Delete(ctx context.Context) error

Delete revokes the wallet key.

func (*WalletKeyService) Get added in v1.0.0 

func (s *WalletKeyService) Get(ctx context.Context) (*WalletKeyInfoResponse, error)

Get returns wallet key info (no plaintext key).

func (*WalletKeyService) Rotate added in v1.0.0 

func (s *WalletKeyService) Rotate(ctx context.Context) (*WalletKeyResponse, error)

Rotate rotates the wallet key. Old key is invalidated immediately.

type WalletListItem added in v1.0.0 

type WalletListItem struct {
	WalletID  string     `json:"walletId"`
	Name      string     `json:"name"`
	CreatedAt *time.Time `json:"createdAt"`
}

WalletListItem represents a wallet in the list response.

type WalletsService 

type WalletsService struct {
	// contains filtered or unexported fields
}

WalletsService handles account-level wallet operations.

func (*WalletsService) Create 

func (s *WalletsService) Create(ctx context.Context) (*CreateWalletResponse, error)

Create creates a new wallet. Requires user key authentication.

func (*WalletsService) List added in v1.0.0 

func (s *WalletsService) List(ctx context.Context) ([]WalletListItem, error)

List returns all wallets for the authenticated user.

type Webhook 

type Webhook struct {
	ID        string     `json:"id"`
	URL       string     `json:"url"`
	Active    bool       `json:"active"`
	CreatedAt *time.Time `json:"createdAt"`
}

Webhook represents a webhook endpoint.

type WebhookWithSecret 

type WebhookWithSecret struct {
	ID        string     `json:"id"`
	URL       string     `json:"url"`
	Secret    string     `json:"secret"`
	CreatedAt *time.Time `json:"createdAt"`
}

WebhookWithSecret is returned when a webhook is created. It includes the secret used for signature verification.

type WebhooksService 

type WebhooksService struct {
	// contains filtered or unexported fields
}

WebhooksService handles wallet-scoped webhook operations.

func (*WebhooksService) Create 

func (s *WebhooksService) Create(ctx context.Context, params *CreateWebhookParams) (*WebhookWithSecret, error)

Create registers a new webhook endpoint.

func (*WebhooksService) Delete 

func (s *WebhooksService) Delete(ctx context.Context, id string) error

Delete removes a webhook endpoint.

func (*WebhooksService) List 

func (s *WebhooksService) List(ctx context.Context) ([]Webhook, error)

List returns all registered webhooks for the wallet.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.