lumenjoule-sdk

Pay for AI inference with USDC or LumenJoule on Stellar. Handles the x402 payment protocol automatically — your agent sends a chat request, the SDK detects the 402, builds a signed payment from your smart wallet, and retries.

Install

npm install lumenjoule-sdk

Smart Wallet Client (Recommended)

Pays from a C-address smart wallet with on-chain spend policies. Works with Ed25519 agent keys (keypair) or Secp256r1 keys (Secure Enclave / software P-256).

import { SmartWalletClient } from "lumenjoule-sdk";

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

const response = await client.chat({
  model: "meta-llama/Llama-3.3-70B-Instruct",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(response.choices[0].message.content);
console.log("TX:", response._payment.transaction);

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | walletAddress | string | required | Smart wallet C-address | | agentSecretKey | string | - | Ed25519 secret key (S...) | | signer | AgentSigner | - | Pluggable signer (alternative to agentSecretKey) | | computeUrl | string | https://compute.lumenbro.com | Compute server URL | | network | "testnet" \| "mainnet" | "mainnet" | Stellar network | | rpcUrl | string | auto | Custom Soroban RPC URL | | preferredAsset | string | USDC SAC | Payment asset (defaults to USDC) | | policyAddress | string | - | Spend policy contract for budget queries |

Methods

client.chat(request) — OpenAI-compatible chat completion with automatic x402 payment.

client.payAndFetch(url, init?) — Generic x402 payment for any endpoint.

client.transfer(token, to, amount) — Direct token transfer (Ed25519 only, agent pays gas).

client.usdcBalance() — USDC balance of the smart wallet (7-decimal stroops).

client.balance(token?) — Token balance query (defaults to LumenJoule).

client.gasBalance() — XLM balance (for gas estimation).

Spend Policy Queries

Requires policyAddress in config. Returns values in 7-decimal stroops (divide by 1e7 for USD).

const client = new SmartWalletClient({
  agentSecretKey: process.env.AGENT_SECRET,
  walletAddress: "CXXX...",
  policyAddress: "CBRGH27ZFVFDIHYKC4K3CSLKXHQSR5CFG2PLPZ2M37NH4PYBOBTTQAEC", // $50/day
});

const budget = await client.budgetStatus();
console.log(`Limit: $${budget.dailyLimitUsdc}`);
console.log(`Spent: $${budget.spentTodayUsdc}`);
console.log(`Left:  $${budget.remainingUsdc}`);

Individual queries: client.dailyLimit(), client.spentToday(), client.remaining().

Mainnet policy tiers: | Tier | Daily Limit | Contract | |------|-------------|----------| | Starter | $50/day | CBRGH27ZFVFDIHYKC4K3CSLKXHQSR5CFG2PLPZ2M37NH4PYBOBTTQAEC | | Production | $500/day | CCRIFGLMG3PT7R3V2IFSRNDNKR2Y2DLJAI5KXYBKNJPFCL2QC4MDIZNJ | | Enterprise | $2,000/day | CCSPAXNEVBNA5QAEU2YEUTU56O5KOZM4C2O7ONQ6GFPSHEWV5OJJS5H2 |

Pluggable Signers

The SDK supports multiple signer types for smart wallet authentication.

Ed25519 (Default)

Standard Stellar keypair. Provide agentSecretKey or use Ed25519AgentSigner directly.

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

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

Secp256r1 — Secure Enclave (macOS)

Hardware-bound P-256 keys via keypo-signer. Keys never leave the Secure Enclave.

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...",
});

Secp256r1 — Software P-256 (Cross-Platform)

Software ECDSA P-256 keys for development/testing on any platform. Keys stored encrypted on disk.

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

// Generate a new key (first time)
const signer = await SoftP256Signer.generate("my-password");

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

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

LumenJoule Client (Legacy)

Pays from a G-address keypair using LumenJoule tokens directly.

import { LumenJouleClient } from "lumenjoule-sdk";

const client = new LumenJouleClient({
  secretKey: "SXXXX...",
  network: "mainnet",
});

const response = await client.chat({
  model: "meta-llama/Llama-3.3-70B-Instruct",
  messages: [{ role: "user", content: "Hello!" }],
});

x402 Protocol Helpers

Lower-level helpers for custom x402 integrations.

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

// Parse 402 response headers
const requirements = await parsePaymentRequirements(response);

// Encode payment for retry
const headers = encodePaymentHeaders(payloadJson);

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

Links

• Agent Portal — Register wallets + agent keys
• LumenJoule Token
• x402 Protocol
• GitHub