From 30687331d8c6b007a5e46bd195951560b4bb5639 Mon Sep 17 00:00:00 2001 From: lightchainaidev Date: Sat, 10 Oct 2026 07:17:20 +0200 Subject: [PATCH] README: say which mode tops up the balance by itself The default mode deposits on a 402 when given a wallet; x402 mode only signs payments and never deposits, so an empty balance answers 402 insufficient_funds. --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 100a75f..7b2b334 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # @lightchainai/sdk -The LightChain AI Developer API for TypeScript: it runs an API key against the right network, and, given a wallet, pays a `402` by itself. Completions go through the OpenAI SDK: the Developer API is OpenAI-compatible. +The LightChain AI Developer API for TypeScript: it runs an API key against the right network, and, given a wallet, pays for calls by itself: it tops up the prepaid balance on a `402` (the default mode), or signs each call's x402 payment (x402 mode). Completions go through the OpenAI SDK: the Developer API is OpenAI-compatible. ```sh npm install @lightchainai/sdk openai @@ -34,7 +34,7 @@ Until the wallet behind the key has paid, and whenever its balance or allowance ## Automatic top-ups -To run a bot unattended, give it the wallet behind the key as `account` (a viem local account). On a `402` for an empty balance or allowance, `lc.fetch` then sends the `depositAndAuthorize` the 402 names from that wallet, and sends the request again. +To run a bot unattended, give it the wallet behind the key as `account` (a viem local account). On a `402` for an empty balance or allowance, `lc.fetch` then sends the `depositAndAuthorize` the 402 names from that wallet, and sends the request again. This is the default mode (`payment: "delegate"`): x402 mode never deposits by itself (see below). ```ts import { privateKeyToAccount } from "viem/accounts"; @@ -56,7 +56,7 @@ Each 402 pays its own deposit, one transaction after the other. Calls made toget ## x402: pay per request -With `payment: "x402"`, the SDK pays each call from the account's own prepaid balance with a signed debit authorization ([x402](https://x402.org), LightChain's `prepaid-debit` scheme). The account authorizes no delegate and sends no transaction per call; it deposits once. It needs `account`, and either an API key or `keyless: true`. +With `payment: "x402"`, the SDK pays each call from the account's own prepaid balance with a signed debit authorization ([x402](https://x402.org), LightChain's `prepaid-debit` scheme). The account authorizes no delegate and sends no transaction per call. The SDK never deposits in this mode: fund the balance yourself with `lc.deposit(value)`. When it can't cover a call, the call fails with `402` `insufficient_funds`: deposit again and retry. It needs `account`, and either an API key or `keyless: true`. ```ts import OpenAI from "openai"; @@ -72,7 +72,7 @@ const lc = new Lightchain({ onPayment: (p) => console.log(`settled in ${p.hash}, ${p.amount} wei debited`), }); -await lc.deposit(10n ** 18n); // once: fund the prepaid balance; it authorizes nobody +await lc.deposit(10n ** 18n); // fund the prepaid balance, and again when it runs out; it authorizes nobody const openai = new OpenAI({ baseURL: lc.baseURL, apiKey: lc.apiKey, fetch: lc.fetch }); const completion = await openai.chat.completions.create({ @@ -95,8 +95,8 @@ Before signing, the SDK checks the requirements against the network it was given | Mode | `apiKey` | `account` | | --- | --- | --- | -| default (`payment: "delegate"`) | required | optional: with it, `fetch` pays a 402 (`depositWei`, `onDeposit`) | -| `payment: "x402"` | required, unless `keyless: true` | required: it signs each payment (`maxPaymentWei`, required, `onPayment`) | +| default (`payment: "delegate"`) | required | optional: with it, `fetch` tops up the balance on a 402 (`depositWei`, `onDeposit`) | +| `payment: "x402"` | required, unless `keyless: true` | required: it signs each payment and never deposits (`maxPaymentWei`, required, `onPayment`) | The constructor throws on any other combination, and on an option the mode would ignore.