Quickstart

In ten minutes you will install the Oris SDK, register an agent, set a spending policy, send a signed payment intent, and verify the resulting compliance bundle on the live verifier. The same flow runs on Python and TypeScript.

Prerequisites

Account

Runtime

Python 3.10 or later, or Node.js 20 or later. The SDK is published on PyPI and npm.

Network

Base Sepolia is wired up out of the box. Mainnet adapters land in a future release.

Time

Ten minutes end to end. Five if you copy and paste.

pip install oris-sdk

The current PyPI release is oris-sdk 0.2.0. Pin the version in production:

pip install "oris-sdk==0.2.0"

npm install oris-sdk

The current npm release is oris-sdk 0.4.0. Pin the version in production:

npm install oris-sdk@0.4.0

2. Configure credentials

You need two values from the dashboard: an API key (oris_sk_live_...) and the private Ed25519 signing key. Store them in environment variables.

export ORIS_API_KEY="oris_sk_live_..."
export ORIS_PRIVATE_KEY="oris_pk_live_..."

3. Register an agent

Every payment Oris signs starts with an agent that has a verified identity. Create one and walk it through KYA Level 1 (developer attestation).

Python
TypeScript

import os
from oris import OrisClient

client = OrisClient(
    api_key=os.environ["ORIS_API_KEY"],
    private_key=os.environ["ORIS_PRIVATE_KEY"],
)

agent = client.agents.create(
    name="procurement-bot",
    description="Buys cloud compute credits.",
)

client.agents.promote(agent.id, target_level=1, attestation="kyb_dev")
print(f"agent.id={agent.id} kya={agent.kya_level}")

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: 'Buys cloud compute credits.',
});

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

console.log(`agent.id=${agent.id} kya=${agent.kyaLevel}`);

The agent starts at Level 0 with zero spending rights. Level 1 enables low-cap payments on a single chain. Higher levels open multi-chain access and higher limits as you attach more attestations. See the KYA feature page for the full ladder.

4. Set a spending policy

Six rule primitives compose a spending envelope. The example below caps a single transaction at fifty dollars, daily spend at five hundred, and only allows a known counterparty whitelist.

Python
TypeScript

client.policies.create(
    agent_id=agent.id,
    max_per_tx=50.00,
    max_daily=500.00,
    max_monthly=5000.00,
    allowed_categories=["cloud_compute", "api_consumption"],
    counterparty_whitelist=["0xA1b2...", "0xC3d4..."],
    escalation_threshold=200.00,
)

await client.policies.create({
  agentId: agent.id,
  maxPerTx: 50.00,
  maxDaily: 500.00,
  maxMonthly: 5000.00,
  allowedCategories: ['cloud_compute', 'api_consumption'],
  counterpartyWhitelist: ['0xA1b2...', '0xC3d4...'],
  escalationThreshold: 200.00,
});

The policy is committed to the L2 registry on Base Sepolia and cached in the policy engine. Evaluation latency runs well under ten milliseconds at p95. See spending policies for the full rule taxonomy.

5. Send a payment

Now the agent can move money. The SDK assembles the compliance bundle (eight layers of signed checks) and submits the verified intent to the configured network adapter.

Python
TypeScript

result = client.payments.send(
    agent_id=agent.id,
    to_address="0xA1b2...",
    amount=12.50,
    chain="base-sepolia",
    category="api_consumption",
)

print(result.bundle_id)
print(result.tx_hash)

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

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

The response carries the bundle id, the on-chain transaction hash, and the signed verdict from the L6 verifier. The bundle anchors hourly into the L7 audit log.

6. Verify a bundle independently

Any party can validate the bundle without trusting the agent or the SDK. The oris.protocol namespace exposes the L8 verifier client.

Python
TypeScript

from oris.protocol import OrisProtocol

p = OrisProtocol(network="base-sepolia")

pubkey = p.verifier.get_pubkey()
verdict = p.verifier.verify(
    bundle_bytes_hex=result.bundle_hex,
    tx_intent_hex=result.tx_intent_hex,
    signer_pubkey_hex=agent.pubkey_hex,
)

assert verdict.allow is True
assert p.verifier.verify_response_signature(verdict, pubkey.pubkey_hex)

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: result.bundleHex,
  txIntentHex: result.txIntentHex,
  signerPubkeyHex: agent.pubkeyHex,
});

if (!verdict.allow) throw new Error('verifier denied');
if (!p.verifier.verifyResponseSignature(verdict, pubkey.pubkeyHex)) {
  throw new Error('verdict signature invalid');
}

The verdict is itself Ed25519-signed by the live verifier. You can cache the pubkey and verify verdicts offline. See offline verification for the cache pattern.

What you just shipped

Eight signed checks

Identity, policy, sanctions, drift, revocation, bundle, verifier, audit. One Ed25519 signature carries them all.

Sub-10 ms policy gate

Every payment passes through the L2 policy engine before any network sees the request.

Hash-chained audit

Every action logged on the L7 audit trail, hourly merkle root anchored to Base.

Two paths to verify

Online against api.useoris.xyz, or offline with a cached pubkey.

Next steps

Read the protocol overview to understand the eight layers your payment just traversed.
Add multi-chain coverage by following the multi-chain feature page.
Connect a BYOK custody provider (Turnkey, Fireblocks, Circle) on the BYOK custody page.
Wire the regulator portal if your jurisdiction expects SAR-grade audit access.

Stuck? Send a note to hello@useoris.xyz. We answer.