joule-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LumenBro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,178 @@
+# joule-sdk
+
+Pay for AI inference with JOULE tokens on Stellar. Your agent sends a prompt, the SDK handles payment automatically via the [x402](https://www.x402.org/) HTTP payment protocol.
+
+```
+Agent sends prompt → gets 402 → signs JOULE transfer → retries with payment → gets inference
+```
+
+One function call. No API keys. No subscriptions. Just tokens and compute.
+
+## Quick Start
+
+```bash
+npm install joule-sdk
+```
+
+```typescript
+import { JouleClient } from "joule-sdk";
+
+const client = new JouleClient({
+  secretKey: "SXXX...",  // Agent's Stellar secret key
+  network: "testnet",
+});
+
+const response = await client.chat({
+  model: "meta-llama/Llama-3.3-70B-Instruct",
+  messages: [{ role: "user", content: "Explain quantum computing" }],
+});
+
+console.log(response.choices[0].message.content);
+console.log(response._payment.transaction); // On-chain tx hash
+```
+
+That's it. The SDK:
+1. Requests inference from the compute server
+2. Receives HTTP 402 with JOULE payment requirements
+3. Builds and signs a Soroban token transfer
+4. Retries the request with the signed payment
+5. Returns the AI response + payment receipt
+
+## What is JOULE?
+
+JOULE is a prepaid AI compute credit on the [Stellar](https://stellar.org) blockchain. 1 JOULE = 1,000 Joules of estimated AI inference energy.
+
+- **SEP-41 compliant** Soroban token
+- **x402 compatible** — the HTTP payment protocol for AI agents
+- **Pay-per-query** — no minimums, no commitments
+- Supports open-source models via [DeepInfra](https://deepinfra.com) (Llama, Mistral, Qwen, DeepSeek)
+
+## Available Models
+
+| Model | Tier | Est. Cost |
+|-------|------|-----------|
+| `meta-llama/Llama-3.3-70B-Instruct` | Medium | ~1.60 JOULE |
+| `meta-llama/Llama-3.2-3B-Instruct` | Small | ~0.38 JOULE |
+| `meta-llama/Llama-4-Scout-17B-16E-Instruct` | Medium | ~1.60 JOULE |
+| `mistralai/Mistral-Small-24B-Instruct-2501` | Medium | ~1.60 JOULE |
+| `Qwen/Qwen2.5-72B-Instruct` | Medium | ~1.60 JOULE |
+| `deepseek-ai/DeepSeek-V3` | Large | ~8.96 JOULE |
+| `deepseek-ai/DeepSeek-R1` | Reasoning | ~38.36 JOULE |
+
+Prices are estimates based on energy consumption at default `max_tokens`. Check live pricing:
+
+```typescript
+const models = await client.models();
+```
+
+## API Reference
+
+### `new JouleClient(config)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `secretKey` | `string` | *required* | Stellar secret key (starts with `S`) |
+| `computeUrl` | `string` | `https://compute.lumenbro.com` | Compute server URL |
+| `network` | `"testnet" \| "mainnet"` | `"testnet"` | Stellar network |
+| `rpcUrl` | `string` | auto | Custom Soroban RPC URL |
+
+### `client.chat(request): Promise<ChatResponse>`
+
+OpenAI-compatible chat completion with automatic JOULE payment.
+
+```typescript
+const response = await client.chat({
+  model: "meta-llama/Llama-3.3-70B-Instruct",
+  messages: [
+    { role: "system", content: "You are a helpful assistant." },
+    { role: "user", content: "What is x402?" },
+  ],
+  max_tokens: 500,
+  temperature: 0.7,
+});
+
+// AI response
+console.log(response.choices[0].message.content);
+
+// Payment receipt
+console.log(response._payment.transaction);  // Stellar tx hash
+console.log(response._payment.joulesPaid);   // "0.10 JOULE"
+console.log(response._payment.network);      // "stellar:testnet"
+```
+
+### `client.models(): Promise<ModelsResponse>`
+
+Fetch available models with live JOULE pricing.
+
+### `client.publicKey: string`
+
+The agent's Stellar public key (derived from the secret key).
+
+## How x402 Works
+
+[x402](https://www.x402.org/) turns HTTP 402 ("Payment Required") into a real payment protocol:
+
+```
+┌─────────┐         ┌──────────────────┐         ┌─────────────┐
+│  Agent   │────────>│  Compute Server  │────────>│ Facilitator │
+│ (SDK)    │  POST   │ compute.lumen... │ verify  │ x402.lumen..│
+│          │<────────│                  │<────────│             │
+│          │  402    │                  │ settle  │             │
+│          │────────>│                  │────────>│             │
+│          │ +X-Pay  │                  │         │             │
+│          │<────────│                  │         │             │
+│          │  200+AI │                  │         │             │
+└─────────┘         └──────────────────┘         └─────────────┘
+```
+
+1. Agent requests inference (no payment)
+2. Server returns **402** with JOULE payment requirements
+3. Agent signs a Soroban token transfer and retries with `X-Payment` header
+4. Server asks the facilitator to verify and settle the payment on-chain
+5. Server forwards the request to the inference provider and returns the result
+
+Every payment is a real on-chain Stellar transaction — verifiable on [Stellar Expert](https://stellar.expert/explorer/testnet).
+
+## Running the Example
+
+```bash
+git clone https://github.com/lumenbro/joule-sdk.git
+cd joule-sdk
+npm install
+
+# Set your agent's Stellar secret key
+export AGENT_SECRET=SXXX...
+
+# Run the chat example
+npx tsx examples/chat.ts
+```
+
+## Network Info
+
+| | Testnet | Mainnet |
+|---|---------|---------|
+| JOULE Token | `CBKI6B65...WXBMX` | Coming soon |
+| Compute Server | `compute.lumenbro.com` | `compute.lumenbro.com` |
+| Facilitator | `x402.lumenbro.com` | `x402.lumenbro.com` |
+| Explorer | [stellar.expert/testnet](https://stellar.expert/explorer/testnet) | — |
+
+## For Agent Frameworks
+
+Works with any TypeScript/JavaScript agent framework:
+
+```typescript
+// LangChain-style tool
+const joule = new JouleClient({ secretKey: process.env.AGENT_KEY });
+
+async function queryLLM(prompt: string): Promise<string> {
+  const res = await joule.chat({
+    model: "meta-llama/Llama-3.3-70B-Instruct",
+    messages: [{ role: "user", content: prompt }],
+  });
+  return res.choices[0].message.content;
+}
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,25 @@
+import type { JouleClientConfig, ChatRequest, ChatResponse } from "./types";
+export declare class JouleClient {
+    private keypair;
+    private computeUrl;
+    private network;
+    private rpcUrl?;
+    constructor(config: JouleClientConfig);
+    /** Agent's public Stellar address */
+    get publicKey(): string;
+    /**
+     * Send a chat completion request, automatically handling x402 payment.
+     *
+     * Flow:
+     * 1. POST to /api/v1/chat/completions (no payment)
+     * 2. Get 402 → extract payment requirements
+     * 3. Build + sign Soroban transfer
+     * 4. Retry with X-Payment header
+     * 5. Return inference response + payment metadata
+     */
+    chat(request: ChatRequest): Promise<ChatResponse>;
+    /**
+     * Get available models and their JOULE pricing.
+     */
+    models(): Promise<any>;
+}

package/dist/client.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JouleClient = void 0;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const wallet_1 = require("./wallet");
+const DEFAULT_COMPUTE_URL = "https://compute.lumenbro.com";
+class JouleClient {
+    constructor(config) {
+        this.keypair = stellar_sdk_1.Keypair.fromSecret(config.secretKey);
+        this.computeUrl = (config.computeUrl || DEFAULT_COMPUTE_URL).replace(/\/$/, "");
+        this.network = config.network || "testnet";
+        this.rpcUrl = config.rpcUrl;
+    }
+    /** Agent's public Stellar address */
+    get publicKey() {
+        return this.keypair.publicKey();
+    }
+    /**
+     * Send a chat completion request, automatically handling x402 payment.
+     *
+     * Flow:
+     * 1. POST to /api/v1/chat/completions (no payment)
+     * 2. Get 402 → extract payment requirements
+     * 3. Build + sign Soroban transfer
+     * 4. Retry with X-Payment header
+     * 5. Return inference response + payment metadata
+     */
+    async chat(request) {
+        const url = `${this.computeUrl}/api/v1/chat/completions`;
+        // Step 1: Initial request (expect 402)
+        const initialResponse = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ ...request, stream: false }),
+        });
+        // If we get 200, the endpoint doesn't require payment (shouldn't happen, but handle it)
+        if (initialResponse.ok) {
+            return initialResponse.json();
+        }
+        // Not a 402? It's an actual error
+        if (initialResponse.status !== 402) {
+            const errorBody = await initialResponse.json().catch(() => ({}));
+            throw new Error(`Compute server error (${initialResponse.status}): ${errorBody?.error?.message || "Unknown error"}`);
+        }
+        // Step 2: Extract payment requirements from 402 response
+        const errorBody = await initialResponse.json();
+        const requirements = errorBody.paymentRequirements;
+        if (!requirements) {
+            throw new Error("402 response missing paymentRequirements — is this an x402-enabled endpoint?");
+        }
+        // Step 3: Build and sign Soroban transfer
+        const paymentPayload = await (0, wallet_1.buildSignedPayment)(this.keypair, requirements, this.network, this.rpcUrl);
+        // Step 4: Encode as base64 and retry with X-Payment header
+        const paymentHeader = Buffer.from(JSON.stringify(paymentPayload)).toString("base64");
+        const paidResponse = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-Payment": paymentHeader,
+            },
+            body: JSON.stringify({ ...request, stream: false }),
+        });
+        if (!paidResponse.ok) {
+            const paidError = await paidResponse.json().catch(() => ({}));
+            throw new Error(`Payment failed (${paidResponse.status}): ${paidError?.error?.message || "Unknown error"}`);
+        }
+        // Step 5: Return response with payment metadata
+        return paidResponse.json();
+    }
+    /**
+     * Get available models and their JOULE pricing.
+     */
+    async models() {
+        const response = await fetch(`${this.computeUrl}/api/models`);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch models: ${response.status}`);
+        }
+        return response.json();
+    }
+}
+exports.JouleClient = JouleClient;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { JouleClient } from "./client";
+export { buildSignedPayment } from "./wallet";
+export type { JouleClientConfig, ChatRequest, ChatResponse, ChatMessage, PaymentRequirements, PaymentPayload, } from "./types";

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSignedPayment = exports.JouleClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "JouleClient", { enumerable: true, get: function () { return client_1.JouleClient; } });
+var wallet_1 = require("./wallet");
+Object.defineProperty(exports, "buildSignedPayment", { enumerable: true, get: function () { return wallet_1.buildSignedPayment; } });

package/dist/types.d.ts

@@ -0,0 +1,68 @@
+export interface JouleClientConfig {
+    /** Agent's Stellar secret key (starts with S...) */
+    secretKey: string;
+    /** Compute server URL (default: https://compute.lumenbro.com) */
+    computeUrl?: string;
+    /** Soroban RPC URL (default: https://soroban-testnet.stellar.org) */
+    rpcUrl?: string;
+    /** Stellar network (default: testnet) */
+    network?: "testnet" | "mainnet";
+}
+export interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+export interface ChatRequest {
+    model: string;
+    messages: ChatMessage[];
+    max_tokens?: number;
+    temperature?: number;
+    top_p?: number;
+    stream?: boolean;
+    stop?: string | string[];
+}
+export interface ChatChoice {
+    index: number;
+    message: ChatMessage;
+    finish_reason: string;
+}
+export interface ChatResponse {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: ChatChoice[];
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    _payment: {
+        transaction: string;
+        network: string;
+        payer: string;
+        joulesPaid: string;
+    };
+}
+export interface PaymentRequirements {
+    scheme: string;
+    network: string;
+    maxAmountRequired: string;
+    resource: string;
+    description: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    asset: string;
+}
+export interface PaymentPayload {
+    x402Version: number;
+    scheme: string;
+    network: string;
+    payload: {
+        signedTxXdr: string;
+        sourceAccount: string;
+        amount: string;
+        destination: string;
+        asset: string;
+    };
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+// ─── SDK Configuration ───────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/wallet.d.ts

@@ -0,0 +1,7 @@
+import { Keypair } from "@stellar/stellar-sdk";
+import type { PaymentPayload, PaymentRequirements } from "./types";
+/**
+ * Build, simulate, and sign a Soroban transfer invocation.
+ * Returns a PaymentPayload ready to be base64-encoded as an X-Payment header.
+ */
+export declare function buildSignedPayment(keypair: Keypair, requirements: PaymentRequirements, network: string, rpcUrl?: string): Promise<PaymentPayload>;

package/dist/wallet.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSignedPayment = buildSignedPayment;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
+const SOROBAN_RPC_URLS = {
+    testnet: "https://soroban-testnet.stellar.org",
+    mainnet: "https://rpc.lightsail.network/",
+};
+const NETWORK_PASSPHRASES = {
+    testnet: stellar_sdk_1.Networks.TESTNET,
+    mainnet: stellar_sdk_1.Networks.PUBLIC,
+};
+/**
+ * Build, simulate, and sign a Soroban transfer invocation.
+ * Returns a PaymentPayload ready to be base64-encoded as an X-Payment header.
+ */
+async function buildSignedPayment(keypair, requirements, network, rpcUrl) {
+    const networkPassphrase = NETWORK_PASSPHRASES[network] || stellar_sdk_1.Networks.TESTNET;
+    const sorobanUrl = rpcUrl || SOROBAN_RPC_URLS[network] || SOROBAN_RPC_URLS.testnet;
+    const server = new stellar_sdk_1.rpc.Server(sorobanUrl);
+    const contractId = requirements.asset;
+    const contract = new stellar_sdk_1.Contract(contractId);
+    // Build transfer(from, to, amount) invocation
+    const transferOp = contract.call("transfer", new stellar_sdk_1.Address(keypair.publicKey()).toScVal(), new stellar_sdk_1.Address(requirements.payTo).toScVal(), (0, stellar_sdk_1.nativeToScVal)(BigInt(requirements.maxAmountRequired), { type: "i128" }));
+    // Load agent account for sequence number
+    const account = await server.getAccount(keypair.publicKey());
+    const tx = new stellar_sdk_1.TransactionBuilder(account, {
+        fee: "100000",
+        networkPassphrase,
+    })
+        .addOperation(transferOp)
+        .setTimeout(300)
+        .build();
+    // Simulate to get auth entries and resource fees
+    const simResult = await server.simulateTransaction(tx);
+    if (stellar_sdk_1.rpc.Api.isSimulationError(simResult)) {
+        const errMsg = simResult.error || "Unknown simulation error";
+        throw new Error(`Simulation failed: ${errMsg}`);
+    }
+    // Assemble with auth entries and sign
+    const assembled = stellar_sdk_1.rpc.assembleTransaction(tx, simResult).build();
+    assembled.sign(keypair);
+    const signedXdr = assembled.toXDR();
+    return {
+        x402Version: 1,
+        scheme: "exact",
+        network: `stellar:${network}`,
+        payload: {
+            signedTxXdr: signedXdr,
+            sourceAccount: keypair.publicKey(),
+            amount: requirements.maxAmountRequired,
+            destination: requirements.payTo,
+            asset: contractId,
+        },
+    };
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "joule-sdk",
+  "version": "0.1.0",
+  "description": "Pay for AI inference with JOULE tokens on Stellar — handles x402 payment protocol automatically",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "example": "npx tsx examples/chat.ts"
+  },
+  "keywords": [
+    "joule",
+    "ai",
+    "inference",
+    "llm",
+    "stellar",
+    "soroban",
+    "x402",
+    "micropayments",
+    "agents",
+    "pay-per-query",
+    "compute",
+    "blockchain"
+  ],
+  "author": "LumenBro <hello@lumenbro.com>",
+  "homepage": "https://github.com/lumenbro/joule-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lumenbro/joule-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lumenbro/joule-sdk/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@stellar/stellar-sdk": "14.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.7.0"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT"
+}