Quickstart

devnet preview — all data is replay

The SDK is not yet on npm — the published name is in clearance — and there is no public devnet endpoint yet. Everything below runs on your machine, from a clone of the repository. No account, no API key.

Buy inference on a local devnet

Requirements: a Rust toolchain and Node 22. Two terminals.

Clone and start the local stack
```
git clone <repo> && cd freeside
cargo run -p relay --bin devserver     # http://127.0.0.1:8645
```
This starts a real chain, one node: the production state machine, the production relay with the payment flow, and the indexer read API — the same code that runs devnet, on your loopback.
Run the agent loop
```
cd sdk/typescript && npm install
npm run example:agent
```
The example funds nothing and asks permission from no one: a seeded devnet key buys inference by the request until its budget is spent.
Read your receipts back
```
npm run example:batch     # per-request cost + the book's clearing prints
```
Every purchase settled on the chain you are running. The indexer client reads the account balance that moved, the lease that cleared, and the price prints the auction emitted.

What just happened

request	the relay answers 402 Payment Required with the terms: book, price cap, fee
signature	the SDK signs the lease intent and fill authorization locally — keys never leave your process
clearing	the order clears at the book's uniform price; escrow locks the spend
delivery	the provider's fill returns through the relay as an ordinary chat response
settlement	usage is metered, the provider is paid, your balance is debited — on chain

The full mechanics — including what happens when a provider fails — are traced with real numbers on The protocol.

The SDK

Local signing only. Your keys live in your process and are used only there — the SDK sends signatures over the wire, never a secret. The relay is transport and attribution, not a custodian. A bare OpenAI client holding an API key cannot buy inference on Freeside: buying requires a signature, and the signature is yours.

import { accountAddress, IndexerClient, keyPairFromSeed, RelayClient, toHex0x } from "@freeside/sdk";

const relay = new RelayClient("http://127.0.0.1:8645");
const indexer = new IndexerClient("http://127.0.0.1:8645");

const key = keyPairFromSeed(mySeed);           // your local key — never leaves this process
const address = accountAddress(key.publicKey); // your on-chain identity, derived from the key
const BUDGET = 5000n;

const start = BigInt((await indexer.account(toHex0x(address))).available);
while (start - BigInt((await indexer.account(toHex0x(address))).available) < BUDGET) {
  // call → 402 → sign LOCALLY → retry → consume
  const res = await relay.chat(
    { model: "freeside-chat", messages: [{ role: "user", content: "…" }], max_tokens: 100 },
    address,
    key,
  );
  console.log(res.choices[0].message.content, res.usage);
}

Modules

relay	the 402 challenge → sign-locally → retry chat flow
chat	one-call chatCompletion(...) facade + a direct node-submit client
indexer	read client over the indexer JSON — accounts, leases, prints
keys	Ed25519 key pairs and local signing
tx	sign lease intents, fill authorizations, obligations; the SignedTx envelope
types	canonical struct mirrors + encoders (byte-identical to the chain)
encoding / hash	the canonical byte layout, SHA-256, and the id derivations

Examples

npm run example:agent	agent-loop.ts — flagship: fund → call → 402 → sign locally → retry → consume, looped under a spend budget
npm run example:batch	batch-buyer.ts — submit a batch of completions, track per-request cost and the book's clearing prints
npm run example:provider	provider-bot.ts — post a capacity obligation, monitor provider stats, sign fill activations

Correctness is enforced byte-for-byte: the SDK's test vectors are generated from the Rust consensus types and checked against every encoding, digest, id derivation, and signature. A cross-language test then drives a real chat completion through the dev server and asserts the usage you see equals the balances that moved on chain.

Agents

The agent loop above is the canonical integration: an agent that pays per call, under a budget, signing every purchase itself. Tool-spec and MCP packaging for agent frameworks is not built yet — when it ships it will wrap this same loop, and this page will say so.

Contracts and feeds

Deployed addresses and ABIs publish with the public devnet; today the chain runs locally from your clone. The price feed contract this site serves is documented by its reference implementation in site/stub — one endpoint, no key:

GET /v1/prices   # every category's clearing price, settled on-chain