Quickstart

Get your first AI agent making payments in under 5 minutes.

1 Install the SDK

# Python
pip install oris

# TypeScript / Node.js
npm install @oris/sdk

2 Initialize Your Agent

import oris

agent = oris.Agent(
    api_key="oris_sk_live_...",
    api_secret="oris_ss_live_...",
)

# Register the agent
agent.register(
    external_agent_id="my-trading-bot",
    agent_name="Yield Optimizer",
    platform="langchain",
)

# Verify (KYA Level 1)
agent.verify()

3 Create a Wallet & Set Spending Limits

# Create an ERC-4337 wallet on Base
agent.create_wallet(chain="base")

# Set spending policy
agent.set_policy(
    max_daily=500,
    max_per_tx=50,
    counterparty_whitelist=["0x742d...bD28"],
)

4 Send Your First Payment

# Send 12.50 USDC (KYA + policy + compliance + on-chain)
result = agent.pay(
    to="0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
    amount=12.50,
    purpose="compute_api_call",
)

print(result["status"])  # "confirmed"
print(result["tx_hash"]) # "0x4a8b..."

What happened behind the scenes?

01KYA verification confirmed agent identity

02Spending policy evaluated in <10ms

03Veris AML pre-screen passed in <100ms

04Balance reserved (ACID), UserOp submitted on-chain

Authentication

Oris uses HMAC-SHA256 request signing. Every request must carry five headers.

Required Headers

Header	Description
Authorization	Your API key: `oris_sk_live_...`
X-Request-Signature	HMAC-SHA256 of the canonical request string
X-Timestamp	Unix epoch seconds (30-second tolerance)
X-Nonce	Unique token per request (30-second Redis TTL)
X-Agent-ID	Agent UUID (for agent-scoped operations)

Canonical Request Format

# The signature is computed over this canonical string:
canonical = f"{timestamp}.{METHOD}.{path}.{sha256(body)}"

# Signing key is SHA-256 of your api_secret:
signing_key = sha256(api_secret)

# Signature:
signature = hmac_sha256(signing_key, canonical)

info

The SDK handles signing automatically. You never need to compute HMAC manually unless building a custom client.

SDKs

Official SDKs with automatic HMAC signing, retry logic, and typed responses.

Python SDK

pip install oris

httpx async client
Sync + Async dual interface
Exponential backoff with jitter
Auto Idempotency-Key

TS

TypeScript SDK

npm install @oris/sdk

Axios async client
40+ strict TypeScript interfaces
Cross-language signature compat
Node.js 18+

TypeScript Example

import { Agent } from '@oris/sdk';

const agent = new Agent({
  apiKey: 'oris_sk_live_...',
  apiSecret: 'oris_ss_live_...',
});

await agent.register({
  externalAgentId: 'my-bot',
  agentName: 'Trading Bot',
});
await agent.verify();
await agent.createWallet({ chain: 'base' });
await agent.setPolicy({ maxDaily: 500, maxPerTx: 50 });

const result = await agent.pay({
  to: '0x742d...bD28',
  amount: 12.50,
  purpose: 'compute_api',
});

Agents & KYA

Know Your Agent: cryptographic identity verification for autonomous AI agents.

KYA Levels

L0

Unverified

No transactions

L1

Basic

Developer verified

L2

Enhanced

User auth attested

L3

Full

30+ days baseline

State Machine

PENDING ──verify()──> VERIFIED
VERIFIED ──suspend()──> SUSPENDED
SUSPENDED ──reinstate()──> VERIFIED
SUSPENDED ──revoke()──> REVOKED (terminal)
VERIFIED ──revoke()──> REVOKED (terminal)

Endpoints

POST/api/v1/oris/agents/registerRegister a new agent

GET/api/v1/oris/agents/{agent_id}Get agent profile

POST/api/v1/oris/agents/{agent_id}/kyaKYA state transition

Wallets

ERC-4337 smart accounts with MPC key management. One wallet per agent per chain.

Supported Chains

Base

ERC-4337

Ethereum

ERC-4337

Solana

Squads PDA

Polygon

ERC-4337

Arbitrum

ERC-4337

Endpoints

POST/api/v1/oris/wallets/createCreate wallet

GET/api/v1/oris/wallets/{id}/balanceGet balance

POST/api/v1/oris/wallets/{id}/freezeFreeze wallet

Spending Policies

Programmable rules evaluated in under 10ms. Redis-cached, no database reads on the critical path.

Rule Types

Rule	Description	Example
max_per_transaction	Single transaction ceiling	50.00
max_daily	Rolling 24-hour cap	500.00
max_weekly	Rolling 7-day cap	2000.00
counterparty_whitelist	Only allowed addresses	["0x..."]
velocity_limits	Transactions per hour	100
escalation_rules	Human approval above threshold	1000.00

Payments

11-step payment pipeline: KYA, policy, compliance, reserve, on-chain, post-screen.

Payment Flow

 1. KYA check          Agent must be verified
 2. Wallet resolution   Find wallet for chain
 3. Policy evaluation   <10ms Redis-cached rules
 4. Veris pre-screen    <100ms sanctions + risk
 5. Balance reservation ACID SELECT FOR UPDATE
 6. Record transaction  Insert to hypertable
 7. Increment counters  Redis atomic INCRBYFLOAT
 8. Commit              PostgreSQL commit
 9. Update cache        Redis balance refresh
10. Submit UserOp       Pimlico bundler (async)
11. Post-screen event   RabbitMQ compliance

Endpoints

POST/api/v1/oris/payments/sendSend payment

GET/api/v1/oris/payments/{id}Get payment status

GET/api/v1/oris/payments/agent/{id}List agent payments

Micropayments

Off-chain state channels with sub-cent precision. Redis Lua atomic metering under 5ms.

# Open a micropayment channel
channel = agent.open_channel(
    partyAId="agent-a-uuid",
    partyBId="agent-b-uuid",
    partyADeposit=100.0,
)

# Record a micropayment ($0.003 per API call)
result = agent.meter(
    channelId=channel["id"],
    payerId="agent-a-uuid",
    payeeId="agent-b-uuid",
    payerIsA=True,
    amount=0.003,
)
# latency_us: 1200 (1.2ms)

Endpoints

POST/api/v1/oris/micropayments/channels/openOpen channel

POST/api/v1/oris/micropayments/meterRecord micropayment

WS/api/v1/oris/micropayments/stream/{id}Streaming payments

Marketplace

Agent-to-agent service discovery with SLA tracking, reputation scoring, and AI-arbitrated disputes.

Endpoints

POST/api/v1/oris/marketplace/listingsCreate listing

GET/api/v1/oris/marketplace/listingsSearch services

POST/api/v1/oris/marketplace/ordersPlace order

POST/api/v1/oris/marketplace/disputesFile dispute

GET/api/v1/oris/marketplace/reputation/{id}Get reputation

MCP Server

Use Oris as a native tool in Claude, GPT, or LangChain agents via Model Context Protocol.

Claude Desktop Config

{
  "mcpServers": {
    "oris": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/oris-mcp-server",
      "env": {
        "ORIS_API_KEY": "oris_sk_live_...",
        "ORIS_API_SECRET": "oris_ss_live_...",
        "ORIS_AGENT_ID": "your-agent-uuid"
      }
    }
  }
}

Available Tools

oris_paySend a stablecoin payment

oris_check_balanceQuery wallet balances

oris_get_spendingGet spending summary

oris_find_serviceSearch marketplace

oris_approve_pendingApprove escalated payment

API Reference

Complete endpoint map. All endpoints require HMAC authentication unless noted.

Developers

POST/oris/developers/registerJWT auth

POST/oris/developers/rotate-key

GET/oris/developers/me

Agents

POST/oris/agents/register

GET/oris/agents/{id}

PATCH/oris/agents/{id}

POST/oris/agents/{id}/kya

POST/oris/agents/{id}/kya-level

Wallets

POST/oris/wallets/create

GET/oris/wallets/{id}

GET/oris/wallets/{id}/balance

GET/oris/wallets/agent/{id}

POST/oris/wallets/{id}/freeze

POST/oris/wallets/{id}/unfreeze

Policies

POST/oris/policies

GET/oris/policies/agent/{id}

PATCH/oris/policies/{id}

DEL/oris/policies/{id}

POST/oris/policies/evaluateDry-run

Payments

POST/oris/payments/send

GET/oris/payments/{id}

GET/oris/payments/agent/{id}

Micropayments

POST/oris/micropayments/channels/open

GET/oris/micropayments/channels/{id}

POST/oris/micropayments/channels/{id}/close

POST/oris/micropayments/meter

GET/oris/micropayments/usage/{id}

WS/oris/micropayments/stream/{id}

Marketplace

POST/oris/marketplace/listings

GET/oris/marketplace/listings

POST/oris/marketplace/orders

POST/oris/marketplace/disputes

GET/oris/marketplace/reputation/{id}

Dashboard

GET/oris/dashboard/spending/summaryJWT auth

GET/oris/dashboard/spending/agentsJWT auth

GET/oris/dashboard/spending/timelineJWT auth