Skip to content
Oris Docs
Sign in Get API Key

TypeScript SDK

oris-sdk 0.4.0 on npm

The TypeScript SDK ships every Oris primitive under one package. Promise-based. Strict typed responses (Zod-validated at the edge). Ed25519 request signing built in. Cross-language parity with the Python SDK on every method.

Install

Terminal window
npm install oris-sdk@0.4.0

Requires Node.js 20 or later. Works in Bun and Deno; verified browser-incompatible for security reasons (signing key would be in the bundle).

Quickstart

import { OrisClient } from 'oris-sdk';


const client = new OrisClient({
  apiKey: process.env.ORIS_API_KEY!,
  privateKey: process.env.ORIS_PRIVATE_KEY!,
});


const agent = await client.agents.create({
  name: 'procurement-bot',
  description: '...',
});


await client.agents.promote(agent.id, { targetLevel: 1, attestation: 'kyb_dev' });


const result = await client.payments.send({
  agentId: agent.id,
  toAddress: '0xA1b2...',
  amount: 12.50,
  chain: 'base-sepolia',
});


console.log(result.bundleId, result.txHash);

Module surface

import {
  OrisClient,             // top-level client
  OrisProtocol,           // L8 verifier client (no API key required)
  errors,                 // OrisError, OrisPolicyDeny, etc.
  types,                  // typed shapes for every method
} from 'oris-sdk';

The Python oris.protocol namespace maps to OrisProtocol in TypeScript. Method names use camelCase; shapes are identical.

Resource surface

client.agents          // KYA + identity
client.wallets         // multi-chain wallet primitive
client.policies        // spending rules
client.payments        // send, status, refund
client.micropayments   // channel lifecycle
client.compliance      // screening, attestation
client.audit           // log verify + list
client.marketplace     // list, search, order, settle
client.treasury        // balances, refill, hierarchical budgets
client.providerKeys    // BYOK

Authentication

Same Ed25519 signing scheme as Python. The SDK builds and signs the canonical payload automatically.

const client = new OrisClient({
  apiKey: 'oris_sk_live_...',
  privateKey: 'oris_pk_live_...',
  // Optional
  baseUrl: 'https://api.useoris.xyz',
  timeoutMs: 30_000,
  maxRetries: 3,
});

The protocol export

import { OrisProtocol } from 'oris-sdk';


const p = new OrisProtocol({ network: 'base-sepolia' });


const pubkey = await p.verifier.getPubkey();


const verdict = await p.verifier.verify({
  bundleBytesHex: bundleHex,
  txIntentHex: txIntentHex,
  signerPubkeyHex: agentPubkeyHex,
});


const ok = p.verifier.verifyResponseSignature(verdict, pubkey.pubkeyHex);

No API key required. Suitable for verifiers, networks, and auditors who consume bundles.

Error hierarchy

import { errors } from 'oris-sdk';


try {
  await client.payments.send({ ... });
} catch (e) {
  if (e instanceof errors.OrisPolicyDeny) {
    console.error('policy denied:', e.rule, e.detail);
  } else if (e instanceof errors.OrisSanctionsError) {
    console.error('sanctions hit:', e.matchedSources);
  } else if (e instanceof errors.OrisError) {
    console.error(e);
  }
}

Every HTTP-level error maps to a typed class with the reason code from the verifier verdict.

Forward compatibility

The public API is frozen on the wire. The OrisProtocol namespace is additive: new methods land in minor releases, no breaking removals. v2 ZK proof types ship without changing the SDK surface.

Where to go next