v1.0.0: Wallet-scoped API, integration tests, SSE improvements

- Migrate to wallet-scoped API pattern: client.Wallet(id).Resource.Method()
- Add WalletScope with all sub-resources (Key, Invoices, Payments, Addresses, Transactions, Webhooks, Events, L402)
- Add RegisterAsync, MeAsync, WalletKeyResource
- Add PublicInvoicesResource (CreateForWallet, CreateForAddress)
- Add ResolveAsync for payment target resolution
- Split account-level vs wallet-level operations
- Add 56 integration tests with real API calls (ordered execution)
- Fix SSE deserialization for heartbeat/empty data
- Exclude integration tests from CI/release workflows
- Update README for v1.0.0 wallet-scoped API

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: realbub

.github/workflows/ci.yml

@@ -26,4 +26,4 @@ jobs:
         run: dotnet build --no-restore --warnaserror
 
       - name: Test
-        run: dotnet test --no-build
+        run: dotnet test --no-build --filter "Category!=Integration"

.github/workflows/release.yml

@@ -18,7 +18,7 @@ jobs:
           dotnet-version: 8.0.x
 
       - name: Test
-        run: dotnet test -c Release
+        run: dotnet test -c Release --filter "Category!=Integration"
 
       - name: Pack
         run: dotnet pack src/LnBot/LnBot.csproj -c Release -o ./nupkg

README.md

@@ -11,9 +11,10 @@ Give your AI agents, apps, and services access to Bitcoin over the Lightning Net
 using LnBot;
 using LnBot.Models;
 
-using var client = new LnBotClient("key_...");
+using var client = new LnBotClient("uk_...");
+var w = client.Wallet("wal_...");
 
-var invoice = await client.Invoices.CreateAsync(new CreateInvoiceRequest
+var invoice = await w.Invoices.CreateAsync(new CreateInvoiceRequest
 {
     Amount = 1000,
     Memo = "Coffee",
@@ -34,27 +35,31 @@ dotnet add package LnBot
 
 ## Quick start
 
-### Create a wallet
+### Register an account
 
 ```csharp
 using LnBot;
-using LnBot.Models;
 
 using var client = new LnBotClient();
+var account = await client.RegisterAsync();
+Console.WriteLine(account.PrimaryKey);
+Console.WriteLine(account.RecoveryPassphrase);
+```
 
-var wallet = await client.Wallets.CreateAsync(new CreateWalletRequest
-{
-    Name = "my-agent",
-});
-Console.WriteLine(wallet.PrimaryKey);
+### Create a wallet
+
+```csharp
+using var client = new LnBotClient(account.PrimaryKey);
+var wallet = await client.Wallets.CreateAsync();
+Console.WriteLine(wallet.WalletId);
 ```
 
 ### Receive sats
 
 ```csharp
-using var client = new LnBotClient(wallet.PrimaryKey);
+var w = client.Wallet(wallet.WalletId);
 
-var invoice = await client.Invoices.CreateAsync(new CreateInvoiceRequest
+var invoice = await w.Invoices.CreateAsync(new CreateInvoiceRequest
 {
     Amount = 1000,
     Memo = "Payment for task #42",
@@ -65,7 +70,7 @@ Console.WriteLine(invoice.Bolt11);
 ### Wait for payment (SSE)
 
 ```csharp
-await foreach (var evt in client.Invoices.WatchAsync(invoice.Number))
+await foreach (var evt in w.Invoices.WatchAsync(invoice.Number))
 {
     if (evt.Event == "settled")
     {
@@ -78,7 +83,7 @@ await foreach (var evt in client.Invoices.WatchAsync(invoice.Number))
 ### Send sats
 
 ```csharp
-var payment = await client.Payments.CreateAsync(new CreatePaymentRequest
+var payment = await w.Payments.CreateAsync(new CreatePaymentRequest
 {
     Target = "alice@ln.bot",
     Amount = 500,
@@ -88,8 +93,42 @@ var payment = await client.Payments.CreateAsync(new CreatePaymentRequest
 ### Check balance
 
 ```csharp
-var current = await client.Wallets.CurrentAsync();
-Console.WriteLine($"{current.Available} sats available");
+var info = await w.GetAsync();
+Console.WriteLine($"{info.Available} sats available");
+```
+
+---
+
+## Wallet-scoped API
+
+All wallet operations go through a `WalletScope` obtained via `client.Wallet(walletId)`:
+
+```csharp
+var w = client.Wallet("wal_abc123");
+
+// Wallet info
+var info = await w.GetAsync();
+await w.UpdateAsync(new UpdateWalletRequest { Name = "production" });
+
+// Sub-resources
+w.Key          // Wallet key management (wk_ keys)
+w.Invoices     // Create, list, get, watch invoices
+w.Payments     // Send, list, get, watch, resolve payments
+w.Addresses    // Create, list, delete, transfer Lightning addresses
+w.Transactions // List transaction history
+w.Webhooks     // Create, list, delete webhook endpoints
+w.Events       // Real-time SSE event stream
+w.L402         // L402 paywall authentication
+```
+
+Account-level operations stay on the client:
+
+```csharp
+await client.RegisterAsync();          // Register new account
+await client.MeAsync();               // Get authenticated identity
+await client.Wallets.CreateAsync();    // Create wallet
+await client.Wallets.ListAsync();      // List wallets
+await client.Keys.RotateAsync(0);     // Rotate account key
 ```
 
 ---
@@ -101,7 +140,7 @@ using LnBot.Exceptions;
 
 try
 {
-    var wallet = await client.Wallets.CurrentAsync();
+    var info = await w.GetAsync();
 }
 catch (NotFoundException ex)
 {
@@ -124,7 +163,7 @@ catch (LnBotException ex)
 ## Configuration
 
 ```csharp
-using var client = new LnBotClient("key_...", new LnBotClientOptions
+using var client = new LnBotClient("uk_...", new LnBotClientOptions
 {
     BaseUrl = "https://api.ln.bot",
     Timeout = TimeSpan.FromSeconds(30),
@@ -135,7 +174,7 @@ Or bring your own `HttpClient`:
 
 ```csharp
 var httpClient = new HttpClient();
-using var client = new LnBotClient("key_...", new LnBotClientOptions
+using var client = new LnBotClient("uk_...", new LnBotClientOptions
 {
     HttpClient = httpClient,
 });
@@ -146,22 +185,24 @@ using var client = new LnBotClient("key_...", new LnBotClientOptions
 ## L402 paywalls
 
 ```csharp
+var w = client.Wallet("wal_...");
+
 // Create a challenge (server side)
-var challenge = await client.L402.CreateChallengeAsync(new CreateL402ChallengeRequest
+var challenge = await w.L402.CreateChallengeAsync(new CreateL402ChallengeRequest
 {
     Amount = 100,
     Description = "API access",
     ExpirySeconds = 3600,
 });
 
 // Pay the challenge (client side)
-var result = await client.L402.PayAsync(new PayL402Request
+var result = await w.L402.PayAsync(new PayL402Request
 {
     WwwAuthenticate = challenge.WwwAuthenticate,
 });
 
 // Verify a token (server side, stateless)
-var v = await client.L402.VerifyAsync(new VerifyL402Request
+var v = await w.L402.VerifyAsync(new VerifyL402Request
 {
     Authorization = result.Authorization!,
 });
@@ -172,6 +213,7 @@ var v = await client.L402.VerifyAsync(new VerifyL402Request
 ## Features
 
 - **Zero dependencies** — `System.Net.Http` + `System.Text.Json` only
+- **Wallet-scoped API** — `client.Wallet(id)` returns a typed scope with all sub-resources
 - **Async-first** — every method returns `Task<T>` with `CancellationToken` support
 - **Typed exceptions** — `BadRequestException`, `NotFoundException`, `ConflictException`, `UnauthorizedException`, `ForbiddenException`
 - **SSE support** — `WatchAsync` returns `IAsyncEnumerable<T>` for real-time events

src/LnBot/ILnBotClient.cs

@@ -1,3 +1,4 @@
+using LnBot.Models;
 using LnBot.Resources;
 
 namespace LnBot;
@@ -7,36 +8,27 @@ namespace LnBot;
 /// </summary>
 public interface ILnBotClient : IDisposable
 {
-    /// <summary>Wallet management.</summary>
+    /// <summary>Account-level wallet management (create, list).</summary>
     WalletsResource Wallets { get; }
 
-    /// <summary>Create and query invoices.</summary>
-    InvoicesResource Invoices { get; }
-
-    /// <summary>Send payments.</summary>
-    PaymentsResource Payments { get; }
-
-    /// <summary>Lightning address management.</summary>
-    AddressesResource Addresses { get; }
-
-    /// <summary>Transaction history.</summary>
-    TransactionsResource Transactions { get; }
-
-    /// <summary>Webhook endpoints.</summary>
-    WebhooksResource Webhooks { get; }
-
-    /// <summary>API key management.</summary>
+    /// <summary>Account-level API key management (uk_ keys).</summary>
     KeysResource Keys { get; }
 
-    /// <summary>L402 paywall authentication.</summary>
-    L402Resource L402 { get; }
-
-    /// <summary>Real-time event stream.</summary>
-    EventsResource Events { get; }
+    /// <summary>Public invoice creation (no auth required).</summary>
+    PublicInvoicesResource Invoices { get; }
 
     /// <summary>Backup wallet access.</summary>
     BackupResource Backup { get; }
 
     /// <summary>Restore wallet access.</summary>
     RestoreResource Restore { get; }
+
+    /// <summary>Registers a new account.</summary>
+    Task<RegisterResponse> RegisterAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>Returns the authenticated identity.</summary>
+    Task<MeResponse> MeAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>Returns a wallet-scoped handle.</summary>
+    WalletScope Wallet(string walletId);
 }

src/LnBot/LnBot.csproj

@@ -10,7 +10,7 @@
 
     <!-- NuGet package metadata -->
     <PackageId>LnBot</PackageId>
-    <Version>0.5.0</Version>
+    <Version>1.0.0</Version>
     <Authors>LnBot</Authors>
     <Description>The official .NET SDK for LnBot — Bitcoin for AI Agents. Create wallets, send and receive sats over the Lightning Network.</Description>
     <PackageTags>bitcoin;lightning;lightning-network;lnbot;sdk;payments;sats</PackageTags>

src/LnBot/LnBotClient.cs

@@ -3,6 +3,7 @@
 using System.Text;
 using System.Text.Json;
 using LnBot.Exceptions;
+using LnBot.Models;
 using LnBot.Resources;
 
 namespace LnBot;
@@ -12,7 +13,7 @@ namespace LnBot;
 /// </summary>
 public sealed class LnBotClient : ILnBotClient
 {
-    internal const string Version = "0.5.0";
+    internal const string Version = "1.0.0";
     internal static readonly string DefaultBaseUrl = "https://api.ln.bot";
 
     private static readonly JsonSerializerOptions JsonOptions = new()
@@ -25,32 +26,14 @@ public sealed class LnBotClient : ILnBotClient
     private readonly HttpClient _http;
     private readonly bool _ownsHttpClient;
 
-    /// <summary>Wallet management.</summary>
+    /// <summary>Account-level wallet management (create, list).</summary>
     public WalletsResource Wallets { get; }
 
-    /// <summary>Create and query invoices.</summary>
-    public InvoicesResource Invoices { get; }
-
-    /// <summary>Send payments.</summary>
-    public PaymentsResource Payments { get; }
-
-    /// <summary>Lightning address management.</summary>
-    public AddressesResource Addresses { get; }
-
-    /// <summary>Transaction history.</summary>
-    public TransactionsResource Transactions { get; }
-
-    /// <summary>Webhook endpoints.</summary>
-    public WebhooksResource Webhooks { get; }
-
-    /// <summary>API key management.</summary>
+    /// <summary>Account-level API key management (uk_ keys).</summary>
     public KeysResource Keys { get; }
 
-    /// <summary>L402 paywall authentication.</summary>
-    public L402Resource L402 { get; }
-
-    /// <summary>Real-time event stream.</summary>
-    public EventsResource Events { get; }
+    /// <summary>Public invoice creation (no auth required).</summary>
+    public PublicInvoicesResource Invoices { get; }
 
     /// <summary>Backup wallet access.</summary>
     public BackupResource Backup { get; }
@@ -61,7 +44,7 @@ public sealed class LnBotClient : ILnBotClient
     /// <summary>
     /// Creates a new LnBot client.
     /// </summary>
-    /// <param name="apiKey">API key for authenticated endpoints. Pass null or empty for unauthenticated usage (e.g. wallet creation).</param>
+    /// <param name="apiKey">API key (uk_ or wk_). Pass null for unauthenticated usage (e.g. public invoice creation).</param>
     /// <param name="options">Optional configuration.</param>
     public LnBotClient(string? apiKey = null, LnBotClientOptions? options = null)
     {
@@ -93,18 +76,37 @@ public LnBotClient(string? apiKey = null, LnBotClientOptions? options = null)
         }
 
         Wallets = new WalletsResource(this);
-        Invoices = new InvoicesResource(this);
-        Payments = new PaymentsResource(this);
-        Addresses = new AddressesResource(this);
-        Transactions = new TransactionsResource(this);
-        Webhooks = new WebhooksResource(this);
         Keys = new KeysResource(this);
-        L402 = new L402Resource(this);
-        Events = new EventsResource(this);
+        Invoices = new PublicInvoicesResource(this);
         Backup = new BackupResource(this);
         Restore = new RestoreResource(this);
     }
 
+    /// <summary>
+    /// Registers a new account. Returns user keys and recovery passphrase.
+    /// </summary>
+    public Task<RegisterResponse> RegisterAsync(CancellationToken cancellationToken = default)
+        => PostAsync<RegisterResponse>("/v1/register", null, cancellationToken);
+
+    /// <summary>
+    /// Returns the authenticated identity.
+    /// </summary>
+    public Task<MeResponse> MeAsync(CancellationToken cancellationToken = default)
+        => GetAsync<MeResponse>("/v1/me", cancellationToken);
+
+    /// <summary>
+    /// Returns a wallet-scoped handle for the given wallet ID.
+    /// This is a factory method — it does not make an HTTP call.
+    /// </summary>
+    /// <param name="walletId">The wallet ID (e.g. "wal_abc123").</param>
+    public WalletScope Wallet(string walletId)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(walletId);
+        return new WalletScope(this, walletId);
+    }
+
+    // ── Internal HTTP helpers ──
+
     internal async Task<T> GetAsync<T>(string path, CancellationToken cancellationToken = default)
     {
         using var response = await _http.GetAsync(path, cancellationToken).ConfigureAwait(false);

src/LnBot/Models/Requests.cs

@@ -2,12 +2,6 @@
 
 namespace LnBot.Models;
 
-public sealed class CreateWalletRequest
-{
-    [JsonPropertyName("name")]
-    public string? Name { get; set; }
-}
-
 public sealed class UpdateWalletRequest
 {
     [JsonPropertyName("name")]