DocsSDK reference

SDK reference

Programmatic access to the W3AI runtime. Available for TypeScript and Rust; Python in preview.

Install

bash

# TypeScript
bun add @w3ai/sdk

# Rust
cargo add w3ai

Quickstart

1
Initialize the client
Provide the user's wallet adapter and an RPC endpoint.
2
Declare an intent
Describe the goal, scopes, and budget.
3
Await the receipt
The receipt contains effects, fee split, and on-chain signature.

import { W3AI } from "@w3ai/sdk";

const w3ai = new W3AI({ wallet, rpc: "https://api.mainnet-beta.solana.com" });

const receipt = await w3ai.intent({
  goal: "fetch ETH/USD twap from 3 oracles and post to my contract",
  scopes: ["net:pyth", "net:chainlink", "net:switchboard", "wallet:sign", "chain:write"],
  budget: { max: 0.05 },
});

console.log(receipt.effects, receipt.fee, receipt.split);

Client API

new W3AI(opts)	Constructs a client. opts: { wallet, rpc, endpoint?, telemetry? }
w3ai.intent(req)	Declare an intent; returns a Promise<Receipt>.
w3ai.stream(req)	AsyncIterable of progress events for long-running intents.
w3ai.cancel(id)	Revoke an in-flight intent; partial receipt is still recorded.
w3ai.receipts(filter)	Query historical receipts for the connected wallet.

Defining intents

An intent is a plain object. The runtime is responsible for compiling it into a task graph.

type Intent = {
  goal: string;                          // natural-language objective
  scopes: Scope[];                       // permissions granted
  budget: { max: number; ceiling?: number };  // in W3AI
  deadline?: number;                     // unix ms
  inputs?: Record<string, unknown>;      // typed payload
  context?: { vault?: string };          // optional memory binding
};

Determinism tip

Pass structured inputs instead of relying on the model to parse them from goal. The planner uses input types for routing and produces more predictable plans.

Scope reference

wallet:sign	Request user signatures (simulation-gated).
chain:write	Broadcast a signed transaction.
net:<host>	Outbound HTTPS to a specific host.
fs:read:<path>	Read from a virtual vault path.
fs:write:<path>	Write to a virtual vault path.
agent:spawn	Spawn child capsules.
llm:call	Use a model — billable to the budget.

Events & streaming

for await (const ev of w3ai.stream(intent)) {
  switch (ev.type) {
    case "plan":      console.log("plan", ev.graph);       break;
    case "capsule":   console.log("spawn", ev.id, ev.scope); break;
    case "simulate":  console.log("sim", ev.effects);      break;
    case "sign":      console.log("user signature needed"); break;
    case "settle":    console.log("on-chain", ev.sig);     break;
    case "receipt":   console.log("done", ev.receipt);     break;
  }
}

Errors

E_SCOPE_DENIED	An action attempted without a granted scope.
E_BUDGET_EXHAUSTED	Budget hit before completion; partial receipt produced.
E_SIM_MISMATCH	On-chain effect diverged from simulation; broadcast aborted.
E_NO_OPERATOR	No operator met the capability + reputation threshold.
E_USER_REJECTED	User declined to sign the simulated effect.

Handling errors

try {
  const r = await w3ai.intent(req);
} catch (e) {
  if (e.code === "E_BUDGET_EXHAUSTED" && e.partial) {
    // recover partial work
  }
  throw e;
}

← Previous

Security model

Validator guide