@aithos/sdk

High-level developer SDK for building agentic apps on the Aithos protocol.

@aithos/sdk is the recommended entry point for app developers. It wraps @aithos/protocol-client (low-level cryptography, signed envelopes, DID and mandate primitives) and adds the Aithos-hosted endpoints — the compute proxy for Bedrock / Claude inference and the wallet for Stripe credit-pack top-ups — behind a single, stable, batteries-included surface.

Status

Pre-alpha. The public API may change between releases until 0.1.0. Pin exact versions in production.

Installation

npm install @aithos/sdk @aithos/protocol-client

@aithos/protocol-client is a peer dependency. Apps that already vend their own copy keep using it; the SDK re-exports its primitives so you do not need to import both directly in app code.

Quick start

import { AithosSDK, createIdentity } from "@aithos/sdk";

// 1. Get or restore the user's identity (a key pair + DID).
const identity = await createIdentity();

// 2. Construct the SDK. Endpoints default to the production Aithos hosts;
//    pass `endpoints` to override (staging, self-host, tests).
const sdk = new AithosSDK({ identity });

// 3. Top up the wallet via Stripe Checkout.
const { checkoutUrl } = await sdk.wallet.createTopupSession({
  packId: "credits-100k",
  successUrl: "https://my-app.example.com/?topup=success",
  cancelUrl: "https://my-app.example.com/?topup=cancel",
});
window.location.href = checkoutUrl;

// 4. Once the user has credits, invoke Bedrock through the compute proxy.
const reply = await sdk.compute.invokeBedrock({
  model: "claude-sonnet-4-6",
  mandateId: "mandate:…",
  messages: [{ role: "user", content: "Hello, Aithos!" }],
});

console.log(reply.content);

Delegating compute to an agent — opt-in token spending

To let an agent (or another user, or a third-party app) invoke Bedrock in your name, with your credits, you mint a mandate. Token spending is its own opt-in capability — passing it is a separate, named, validated input that a consent UI can review. It is NEVER an implicit side-effect of an ethos read/write scope.

// Mint a mandate that lets agent Bob read your public ethos AND
// spend up to 5 000 microcredits/day on Haiku, capped at 100 000
// microcredits over the whole mandate lifetime.
const mandate = await sdk.mandates.create({
  granteeId: "urn:agent:bob",
  scopes: ["ethos.read.public"],
  ttlSeconds: 86_400,
  compute: {
    dailyCapMicrocredits: 5_000,
    totalCapMicrocredits: 100_000,
    maxCreditsPerCall: 500,
    allowedModels: ["claude-haiku-4-5"],
  },
});

// Hand `mandate.bundle` (a `.aithos-delegate.json` Blob) to Bob.
// He imports it, then signs his own envelopes and calls
// sdk.compute.invokeBedrock({ mandateId: mandate.mandateId, … })
// — every invocation debits *your* wallet, capped per the budget
// you set.

Three invariants the SDK enforces synchronously, before reaching the network — they fail fast with a precise AithosSDKError:

• No smuggling. Adding "compute.invoke" directly to scopes[] throws mandates_invalid_scopes. The compute namespace is the only path, so a UI reviewing compute can never be bypassed.
• No bearer compute. A compute namespace without at least one of dailyCapMicrocredits or totalCapMicrocredits throws mandates_invalid_compute. Unbounded compute mandates are forbidden by construction.
• Compute-only is fine. scopes: [] is allowed when compute is set — useful for agents that only consume tokens (e.g. creative assistants) without seeing any of your data.

What lives where

License

Apache-2.0 © 2026 Mathieu Colla. See LICENSE.