Weft SDK

Build buyer applications and agents on Weft. The TypeScript SDK and the Python buyer client are the supported application surfaces in this repository. Generated clients remain available when you need direct access to the OpenAPI contract. The weft command-line client is a separate package: weftlabs/weft-cli.

For a source checkout, start with local development tools. The buyer quickstarts below use a real account; they are not local setup checks.

1. Sign in at weft.network.

2. Create a buyer API key in Dashboard → API keys. Copy the one-time wk_* value and keep it out of source control.

3. Install the SDK and set the key in your shell:

   npm install @weftlabs/sdk @x402/core
   export WEFT_API_KEY="wk_..."

4. Create quickstart.mjs:

   import { WeftClient } from "@weftlabs/sdk";
   
   const apiKey = process.env.WEFT_API_KEY;
   if (!apiKey) throw new Error("Set WEFT_API_KEY to a buyer wk_* API key");
   
   const weft = new WeftClient({ apiKey });
   
   const account = await weft.me();
   const search = await weft.search({ query: "weather data API" });
   
   console.log({ account: account.data, results: search.results });

   node quickstart.mjs

WeftClient uses https://weft.network by default. See the TypeScript guide for bounded paid fetches, retries, error handling, and low-level generated APIs. The executable source for the quickstart is shipped in the package at examples/quickstart.mjs.

The command-line client is not in this repository. Install and use it from weftlabs/weft-cli.

The SDK npm package now uses @weftlabs/sdk. To migrate an existing project, replace @weft-labs/sdk in its dependencies and imports, including subpath imports such as /server and /facilitator/middleware.

The CLI package is @weftlabs/cli. For a global CLI installation, uninstall @weft-labs/cli before installing @weftlabs/cli; both packages provide the same weft command.

The old packages remain available for existing installations. This scope change keeps the shared version at 0.25.0 and does not change the public API. If your project uses an older version, check the intervening API changes as part of the upgrade.

“Generated client preview” means the package is published and tracks the API contract, but has not yet passed a clean-install buyer quickstart gate.

• Weft Labs
• API reference
• OpenAPI document
• Weft CLI guide
• x402 in Next.js
• Learn
• x402 protocol
• MPP
• How AI agents buy APIs
• AI agent payments
• TypeScript package guide
• Python package guide
• GitHub issues

• spec/openapi.yaml — canonical contract copy synchronized from weft-app
• typescript/ — npm package @weftlabs/sdk
• python/ — PyPI package weft-sdk
• ruby/ — RubyGems package weft-sdk
• go/ — Go module github.com/weftlabs/weft-sdk/go
• scripts/ — generation, conformance, and release checks

All language packages share a version tied to the OpenAPI version. Generated sources are updated by the spec-sync workflow and must not be edited manually.

Install Git and Mise, and activate Mise in your interactive shell once. Run these blocks separately from the repository root; after tool installation, wait for the next shell prompt before installing dependencies. .mise.toml owns the source runtimes and tools; manifests and lockfiles own package dependencies. Published TypeScript packages still support Node.js 18 or newer; the source build runtime is a separate selection, not the consumer compatibility floor.

TypeScript 7 checks sources with pnpm --filter @weftlabs/sdk run typecheck and runs before each build. ESLint and tsup declaration generation still need the TypeScript 6 JavaScript API, so the typescript dependency uses Microsoft's @typescript/typescript6 compatibility package. The @typescript/native alias supplies TypeScript 7's tsc; the compatibility package supplies tsc6. Vitest 5 runs on the repository's Node 24 toolchain. These development dependencies do not change the published SDK's Node support.

No Weft account, API key, wallet key or provider credential is needed for source installation, builds or unit tests. Use a credential-free environment; do not copy active account configuration into the checkout. Tool/dependency installation needs download access. Review the tool configuration, then:

mise trust
mise install

Then install dependencies and hooks:

pnpm install --frozen-lockfile
uv sync --project python --python "$(mise which python)" --frozen --group dev
cd ruby
bundle config set --local path vendor/bundle
bundle config set --local frozen true
bundle install
cd ..
go -C go mod download
lefthook install

Build the source packages and run the TypeScript unit checks:

pnpm run build
pnpm --filter @weftlabs/sdk run test:unit

package.json owns the build and broader check commands. lefthook.yml owns the language-specific unit gates: pre-commit checks lint or format staged files only; pre-push runs whole-repo lint and format checks plus TypeScript, Python, Ruby and Go unit tests. The Python hook uses the installed environment without dependency sync. Run the setup commands again after dependency changes. Builds, generated-code checks, type checks, quickstarts, and network tests remain in CI.

These packages are libraries, not an API server. Build/unit commands return when finished; there is no persistent SDK service to start or stop. Live buyer/seller examples, staging checks, spec regeneration and publishing are separate operations. Do not use a paid fetch or wallet bootstrap as setup verification, and do not hand-edit generated clients.