Skip to content

README: say which mode tops up the balance by itself #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lightchainaidev merged 1 commit into from
Oct 10, 2026
Merged

README: say which mode tops up the balance by itself #5

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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";
Expand All @@ -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";
Expand All @@ -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({
Expand All @@ -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.

Expand Down
Loading