litd-grpc
starsforks
How to install litd-grpc?
lightninglabs/lightning-agent-tools/litd-grpc
$npx -y skills add lightninglabs/lightning-agent-tools --skill litd-grpcReference for litd (Lightning Terminal) gRPC API in Go: managing accounts, baking macaroons, listing payments, and creating LNC sessions.
SKILL.md
| 1 | # litd gRPC — Accounts & LNC Sessions |
| 2 | |
| 3 | Reference for interacting with litd (Lightning Terminal daemon) gRPC API: managing accounts and LNC sessions, baking account-scoped macaroons, and listing account payments. |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | ## Connection Setup |
| 8 | |
| 9 | litd exposes a single TLS gRPC endpoint (default `localhost:8443`). Authentication uses macaroon hex in the `macaroon` request metadata header. |
| 10 | |
| 11 | ### Bootstrap connection (supermacaroon) |
| 12 | |
| 13 | ```go |
| 14 | import ( |
| 15 | "google.golang.org/grpc" |
| 16 | "google.golang.org/grpc/credentials" |
| 17 | "github.com/lightninglabs/lightning-terminal/litrpc" |
| 18 | "github.com/lightningnetwork/lnd/lnrpc" |
| 19 | ) |
| 20 | |
| 21 | // 1. Load TLS cert |
| 22 | tlsCreds, _ := credentials.NewClientTLSFromFile("~/.lit/tls.cert", "") |
| 23 | |
| 24 | // 2. Wrap the lit.macaroon as a per-RPC credential |
| 25 | creds := &macaroonCredentials{hex: hex.EncodeToString(macBytes)} |
| 26 | |
| 27 | // 3. Dial |
| 28 | conn, _ := grpc.NewClient( |
| 29 | "localhost:8443", |
| 30 | grpc.WithTransportCredentials(tlsCreds), |
| 31 | grpc.WithPerRPCCredentials(creds), |
| 32 | ) |
| 33 | |
| 34 | // 4. Immediately bake a supermacaroon so one credential covers all sub-services |
| 35 | proxy := litrpc.NewProxyClient(conn) |
| 36 | resp, _ := proxy.BakeSuperMacaroon(ctx, &litrpc.BakeSuperMacaroonRequest{}) |
| 37 | creds.update(resp.Macaroon) // swap in supermacaroon; lit.macaroon no longer sent |
| 38 | |
| 39 | // 5. Create sub-clients on the same connection |
| 40 | lightning := lnrpc.NewLightningClient(conn) |
| 41 | accounts := litrpc.NewAccountsClient(conn) |
| 42 | sessions := litrpc.NewSessionsClient(conn) |
| 43 | ``` |
| 44 | |
| 45 | ### macaroonCredentials helper (thread-safe, swappable) |
| 46 | |
| 47 | ```go |
| 48 | type macaroonCredentials struct { |
| 49 | mu sync.RWMutex |
| 50 | hex string |
| 51 | } |
| 52 | func (m *macaroonCredentials) GetRequestMetadata(_ context.Context, _ ...string) (map[string]string, error) { |
| 53 | m.mu.RLock(); defer m.mu.RUnlock() |
| 54 | return map[string]string{"macaroon": m.hex}, nil |
| 55 | } |
| 56 | func (m *macaroonCredentials) RequireTransportSecurity() bool { return true } |
| 57 | func (m *macaroonCredentials) update(h string) { m.mu.Lock(); m.hex = h; m.mu.Unlock() } |
| 58 | ``` |
| 59 | |
| 60 | --- |
| 61 | |
| 62 | ## Account Management |
| 63 | |
| 64 | All account RPCs go through `litrpc.AccountsClient`. |
| 65 | |
| 66 | ### List all accounts |
| 67 | |
| 68 | ```go |
| 69 | resp, err := accounts.ListAccounts(ctx, &litrpc.ListAccountsRequest{}) |
| 70 | // resp.Accounts []*litrpc.Account |
| 71 | // Account fields: Id, Label, CurrentBalance, InitialBalance, ExpirationDate, Payments []*AccountPayment |
| 72 | ``` |
| 73 | |
| 74 | ### Get single account |
| 75 | |
| 76 | ```go |
| 77 | resp, err := accounts.AccountInfo(ctx, &litrpc.AccountInfoRequest{Id: accountID}) |
| 78 | // resp is *litrpc.Account directly |
| 79 | ``` |
| 80 | |
| 81 | ### Create account |
| 82 | |
| 83 | ```go |
| 84 | resp, err := accounts.CreateAccount(ctx, &litrpc.CreateAccountRequest{ |
| 85 | AccountBalance: 100_000, // satoshis; 0 = empty account is valid |
| 86 | Label: "My Budget", // optional |
| 87 | ExpirationDate: 0, // 0 = never; unix timestamp otherwise |
| 88 | }) |
| 89 | // resp.Account *litrpc.Account |
| 90 | ``` |
| 91 | |
| 92 | ### Update account (balance, expiry, label) |
| 93 | |
| 94 | `UpdateAccountRequest` uses sentinel `-1` for `AccountBalance` to mean "do not change balance". |
| 95 | Always pass the **current** `ExpirationDate` when only changing the label (protobuf 0 = unset = may reset expiry). |
| 96 | |
| 97 | ```go |
| 98 | // Credit (add sats) |
| 99 | resp, err := accounts.CreditAccount(ctx, &litrpc.CreditAccountRequest{ |
| 100 | Account: &litrpc.AccountIdentifier{ |
| 101 | Identifier: &litrpc.AccountIdentifier_Id{Id: accountID}, |
| 102 | }, |
| 103 | Amount: 50_000, |
| 104 | }) |
| 105 | |
| 106 | // Debit (remove sats) |
| 107 | resp, err := accounts.DebitAccount(ctx, &litrpc.DebitAccountRequest{ |
| 108 | Account: &litrpc.AccountIdentifier{ |
| 109 | Identifier: &litrpc.AccountIdentifier_Id{Id: accountID}, |
| 110 | }, |
| 111 | Amount: 10_000, |
| 112 | }) |
| 113 | |
| 114 | // Update expiry only |
| 115 | resp, err := accounts.UpdateAccount(ctx, &litrpc.UpdateAccountRequest{ |
| 116 | Id: accountID, |
| 117 | AccountBalance: -1, // do not touch balance |
| 118 | ExpirationDate: newExpiry, |
| 119 | }) |
| 120 | |
| 121 | // Update label only — pass current expiry to avoid clearing it |
| 122 | resp, err := accounts.UpdateAccount(ctx, &litrpc.UpdateAccountRequest{ |
| 123 | Id: accountID, |
| 124 | AccountBalance: -1, |
| 125 | ExpirationDate: currentAccount.ExpirationDate, |
| 126 | Label: "New Label", |
| 127 | }) |
| 128 | ``` |
| 129 | |
| 130 | ### Remove account |
| 131 | |
| 132 | ```go |
| 133 | _, err := accounts.RemoveAccount(ctx, &litrpc.RemoveAccountRequest{Id: accountID}) |
| 134 | ``` |
| 135 | |
| 136 | --- |
| 137 | |
| 138 | ## Macaroon Baking (Account-Scoped) |
| 139 | |
| 140 | Macaroons are baked via `lnrpc.LightningClient.BakeMacaroon`, then a first-party caveat ties them to an account: |
| 141 | |
| 142 | ```go |
| 143 | // 1. Bake base macaroon with desired permissions |
| 144 | resp, _ := lightning.BakeMacaroon(ctx, &lnrpc.BakeMacaroonRequest{ |
| 145 | Permissions: []*lnrpc.MacaroonPermission{ |
| 146 | {Entity: "info", Action: "read"}, |
| 147 | {Entity: "invoices", Action: "read"}, |
| 148 | {Entity: "offchain", Action: "read"}, |
| 149 | {Entity: "onchain", Action: "read"}, |
| 150 | }, |
| 151 | AllowExternalPermissions: true, |
| 152 | }) |
| 153 | |
| 154 | // 2. Decode, add account caveat, re-encode |
| 155 | macBytes, _ := hex.DecodeString(resp.Macaroon) |
| 156 | mac, _ := macaroon.New(nil, nil, "", macaroon.LatestVersion) |
| 157 | mac.UnmarshalBinary |
People who liked this also viewed
6 picksType
- remotion-to-hyperframesPort an existing Remotion (React) composition''s source to HyperFrames HTML. Use ONLY on an explicit ask to port/convert/migrate/translate a Remotion source — one-way, Remotion-only. A passing RemotioSkillsJul 2026
- solana-devUse when user asks to "build a Solana dapp", "write an Anchor program", "create a token", "debug Solana errors", "set up wallet connection", "test my Solana program", "deploy to devnet", or "explain SSkillsJul 2026
- grimoire-polymarketQueries Polymarket market data and CLOB state, and manages CLOB orders via the Grimoire venue CLI wrapper backed by the official Polymarket CLI.SkillsMay 2026
- shopify-storefront-graphqlUse for custom storefronts requiring direct GraphQL queries/mutations for data fetching and cart operations. Choose this when you need full control over data fetching and rendering your own UI. NOT foSkillsJul 2026
- agentic-walletCrypto wallet operations via the awal CLI — sign in, check balances, send USDC/ETH/POL/SOL, trade tokens, fund the wallet, and use the x402 payment protocol to discover paid services, pay for API callSkillsJun 2026
- quicknode-skillQuicknode blockchain infrastructure for 80+ chains: Core RPC API, Streams, Webhooks, Blazar WSS, Solana gRPC, HyperCore gRPC, SQL Explorer, Metaplex DAS API, Blockbook, Ordinals & Runes API, Swap API,SkillsJul 2026
