Agent Wallet SDK

Overview

LumenBro Agents gives AI agents self-custodial wallets on Stellar. Your agent calls any x402-enabled API, the SDK detects the 402, signs a payment from the smart wallet, and retries. No API keys, no custodians, no seed phrases.

1. Create a wallet at agents.lumenbro.com — deploys a Stellar smart account (C-address) secured by your passkey
2. Register an agent signer — Ed25519 keypair or P-256 key, each gated by a daily spend policy
3. Fund with USDC — send USDC to your wallet's C-address
4. Use the SDK — npm install lumenjoule-sdk, call client.chat(), done

Agent keys only sign auth entries (not TX envelopes). The facilitator pays gas and submits the transaction. Agent keys never need XLM funding for x402 payments.

Smart Wallet Architecture

Each wallet is a Stellar smart account (C-address) that acts as a shared vault. Multiple agent signers draw from the same balance, each with independent daily limits.

Smart account contract source: github.com/lumenbro/stellar-smart-account · Spend policy source: github.com/lumenbro/soroban-policies

Quick Start

1. Install

npm install lumenjoule-sdk

Create a wallet at agents.lumenbro.com if you haven't already.

2. Configure

import { SmartWalletClient } from "lumenjoule-sdk";

const client = new SmartWalletClient({
  agentSecretKey: process.env.AGENT_SECRET,  // S... key from portal
  walletAddress: "CXXX...",                   // your wallet C-address
  network: "mainnet",
});

3. Use

const response = await client.chat({
  model: "deepseek-ai/DeepSeek-V3",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(response.choices[0].message.content);

The SDK handles the x402 payment automatically: request → 402 → sign payment → retry → response.

Signer Types

Three signer implementations, same smart wallet. Pick based on your platform and security requirements.

Ed25519 — Stellar Keypair (Any Platform)

The simplest option. Generate a Stellar keypair, register the public key (G-address) as an agent signer in the portal, and pass the secret key to the SDK.

import { SmartWalletClient } from "lumenjoule-sdk";

const client = new SmartWalletClient({
  agentSecretKey: process.env.AGENT_SECRET,   // S... secret key
  walletAddress: "CXXX...",                    // wallet C-address
  network: "mainnet",
});

SoftP256Signer — Software P-256 (Any Platform)

Encrypted P-256 key stored on disk. Same signing format as Secure Enclave — production-ready on Linux VPS, Windows, macOS. AES-256-GCM encryption with PBKDF2-derived key.

import { SmartWalletClient, SoftP256Signer } from "lumenjoule-sdk";

// First time: generate and save encrypted key
const signer = await SoftP256Signer.generate("my-password");
// Saved to: ~/.lumenjoule/agent-key.enc
// Prints: public key (paste into portal when registering Secp256r1 signer)

// After: load existing key
const signer = await SoftP256Signer.load("my-password");

const client = new SmartWalletClient({
  signer,
  walletAddress: "CXXX...",
  network: "mainnet",
});

KeypoSigner — Secure Enclave (macOS)

Hardware-bound P-256 key via keypo-signer. The private key lives in the Secure Enclave and can never be extracted. Install: brew install keypo-signer.

import { SmartWalletClient, KeypoSigner } from "lumenjoule-sdk";

const signer = new KeypoSigner({
  keyLabel: "my-agent-key",
  publicKey: Buffer.from("BASE64_PUBLIC_KEY", "base64"),
});

const client = new SmartWalletClient({
  signer,
  walletAddress: "CXXX...",
  network: "mainnet",
});

Pay Any x402 Endpoint

The wallet isn't limited to one service. payAndFetch() works with any x402-compatible endpoint on any server. chat() is a convenience wrapper for OpenAI-compatible inference APIs.

// AI inference (OpenAI-compatible)
const response = await client.chat({
  model: "deepseek-ai/DeepSeek-V3",
  messages: [{ role: "user", content: "Analyze this data" }],
});

// Any x402 endpoint
const data = await client.payAndFetch("https://some-api.com/v1/data", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ query: "..." }),
});

// Direct USDC transfer (non-x402, agent pays gas)
const txHash = await client.transfer(
  USDC_CONTRACT,
  recipientAddress,
  1_000_000n,  // 0.1 USDC (7 decimals)
);

Spend Policies

Every agent signer is gated by an on-chain ExternalValidatorPolicy contract. The policy is enforced during __check_auth on every transfer and approval. Even if a key is compromised, damage is capped.

Query Budget

// Requires policyAddress in constructor
const client = new SmartWalletClient({
  agentSecretKey: process.env.AGENT_SECRET,
  walletAddress: "CXXX...",
  policyAddress: "CBRGH27Z...",  // Starter tier
});

const budget = await client.budgetStatus();
// { dailyLimitUsdc: 50, spentTodayUsdc: 3.20, remainingUsdc: 46.80 }

// Individual queries
const limit     = await client.dailyLimit();    // 500_000_000n (stroops)
const spent     = await client.spentToday();    // 32_000_000n
const remaining = await client.remaining();     // 468_000_000n

x402 Payment Protocol

The SDK implements the x402 payment protocol for Stellar. Compatible with both the LumenBro facilitator and the OpenZeppelin Stellar facilitator.

The facilitator is a neutral relay — it doesn't need to understand smart wallets or signer types. It receives pre-signed auth entries, rebuilds the TX, and submits. The Soroban runtime calls __check_auth on your wallet contract transparently.

API Reference

SmartWalletClient Constructor

Methods

x402 Protocol Helpers

import { parsePaymentRequirements, performX402Dance } from "lumenjoule-sdk";

// Parse 402 response headers
const requirements = parsePaymentRequirements(response);
// { scheme, payTo, amount, asset, network, maxTimeoutSeconds, ... }

// Full dance: request -> 402 -> build payment -> retry
const paidResponse = await performX402Dance(url, init, buildPaymentFn);

Compute Server API

The default x402 endpoint for client.chat(). OpenAI-compatible, accepts USDC payments via x402.

Base URL: https://compute.lumenbro.com

You can point computeUrl to any x402-compatible inference server. The wallet is not locked to LumenBro compute.

Why Self-Custody Matters

Your agent's signing key lives on your device. The server never touches private keys — it only wraps transactions for gas sponsorship.

If your wallet provider goes down or changes terms, your agent's wallet should still work. With self-custody, it does. The server is only a gas sponsor — it fee-bumps pre-signed transactions but never has access to your keys.

FAQ

Resources

• Agent Portal — Create wallets + register agent signers
• lumenjoule-sdk on npm
• SDK on GitHub
• x402 Protocol Specification
• LumenJoule Token
• LumenJoule on StellarExpert
• Stellar