Quickstart

This guide takes you from zero to a confirmed payment in under 5 minutes. You will register as a developer, create an agent, set a spending policy, and execute a stablecoin payment on Base.

Prerequisites

✓ Python 3.9+ or Node.js 18+
✓ An Oris API key (get one at useoris.ai)

1 Install the SDK

Terminal
$ pip install oris

Terminal
$ npm install @oris/sdk

2 Initialize the Client

Create an agent instance with your API credentials. The SDK handles HMAC signing, retries, and error mapping automatically.

quickstart.py

from oris import Agent

agent = Agent(
    api_key="oris_sk_live_your_key_here",
    api_secret="oris_ss_live_your_secret_here"
)

quickstart.ts

import { Agent } from '@oris/sdk'

const agent = new Agent({
  apiKey: 'oris_sk_live_your_key_here',
  apiSecret: 'oris_ss_live_your_secret_here'
})

3 Register and Verify the Agent

Every agent starts at KYA Level 0 (pending). Call verify() to promote to Level 1, which unlocks transaction capabilities.

# Register the agent
result = agent.register(
    name="my-trading-bot",
    platform="openai",
    agent_type="autonomous"
)
print(result.id)          # "550e8400-..."
print(result.kya_status)  # "pending"
print(result.kya_level)   # 0

# Verify to unlock transactions
transition = agent.verify()
print(transition.new_status)  # "verified"
print(transition.new_level)   # 1

// Register the agent
const result = await agent.register({
  externalAgentId: 'my-trading-bot',
  agentName: 'My Trading Bot',
  platform: 'openai'
})
console.log(result.id)          // "550e8400-..."
console.log(result.kya_status)  // "pending"

// Verify to unlock transactions
const transition = await agent.verify()
console.log(transition.new_status)  // "verified"

4 Create a Wallet

Create an ERC-4337 smart account wallet on Base. The system generates a new wallet address and links it to your agent.

wallet = agent.create_wallet(chain="base")
print(wallet.id)                     # "660e8400-..."
print(wallet.smart_account_address)  # "0x1234..."
print(wallet.chain)                  # "base"
print(wallet.wallet_type)            # "erc4337"

const wallet = await agent.createWallet({ chain: 'base' })
console.log(wallet.smart_account_address)  // "0x1234..."

Fund the wallet. Send USDC to the smart_account_address on Base before making payments. The system verifies balance before every transaction.

5 Set a Spending Policy

Define spending limits for the agent. The policy engine evaluates every payment against these rules in under 10ms.

policy = agent.set_policy(
    max_per_tx=50,       # $50 per transaction
    max_daily=500,       # $500 per day
    enforcement_mode="enforce"  # reject violations
)

# Simulate before sending real payments
sim = agent.simulate_payment(amount=75)
print(sim.passed)          # False
print(sim.violated_rules)  # ["max_per_transaction"]

await agent.setPolicy({
  maxPerTx: 50,
  maxDaily: 500,
  enforcementMode: 'enforce'
})

// Simulate before sending real payments
const sim = await agent.simulatePayment({ amount: 75 })
console.log(sim.passed)          // false
console.log(sim.violated_rules)  // ["max_per_transaction"]

6 Execute a Payment

Send USDC to a counterparty address. The system runs policy evaluation and Veris compliance screening before submitting the transaction on-chain.

payment = agent.pay(
    to="0x7f3a9c2d...",
    amount=12.50,
    stablecoin="USDC",
    chain="base",
    purpose="API access"
)

print(payment.id)               # "770e8400-..."
print(payment.status)           # "pending"
print(payment.policy_result)    # "passed"
print(payment.veris_pre_screen) # "allow"
print(payment.protocol)         # "x402"

const payment = await agent.pay({
  to: '0x7f3a9c2d...',
  amount: 12.50,
  stablecoin: 'USDC',
  chain: 'base',
  purpose: 'API access'
})

console.log(payment.status)           // "pending"
console.log(payment.veris_pre_screen) // "allow"

Payment Flow

When you call pay(), the system executes these steps in order:

Step	Description	Latency
1. KYA tier gate	Verify agent KYA level permits the protocol and amount	<1ms
2. Policy evaluation	Check all active spending policies (Redis cached)	<10ms
3. Compliance pre-screen	Veris sanctions screening + risk scoring (fail-closed)	<100ms
4. Balance reservation	Atomic SELECT FOR UPDATE on wallet balance	<5ms
5. On-chain submission	ERC-4337 UserOp or Solana TX via Celery worker	async
6. Post-screen	Veris deep analysis via RabbitMQ (background)	async

Response Fields

Field	Type	Description
`id`	string	Payment UUID
`status`	string	`pending` \| `submitted` \| `confirmed` \| `failed` \| `rejected`
`policy_result`	string	`passed` \| `violated` \| `escalated`
`veris_pre_screen`	string	`allow` \| `enhanced_review` \| `block`
`tx_hash`	string?	On-chain transaction hash (populated after confirmation)
`amount`	string	Transaction amount in decimal
`protocol`	string	Payment protocol used (`x402`, `direct`, etc.)

Complete Example

complete_quickstart.py

from oris import Agent

# 1. Initialize
agent = Agent(
    api_key="oris_sk_live_...",
    api_secret="oris_ss_live_..."
)

# 2. Register and verify
agent.register(name="my-bot", platform="openai")
agent.verify()

# 3. Create wallet on Base
wallet = agent.create_wallet(chain="base")
print(f"Fund this address: {wallet.smart_account_address}")

# 4. Set spending policy
agent.set_policy(max_per_tx=50, max_daily=500)

# 5. Execute payment
result = agent.pay(to="0x7f3a...", amount=12.50)
print(f"Payment {result.id}: {result.status}")
print(f"Policy: {result.policy_result}")
print(f"Compliance: {result.veris_pre_screen}")

quickstart.ts

import { Agent } from '@oris/sdk'

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

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

const result = await agent.pay({ to: '0x7f3a...', amount: 12.50 })
console.log(result.status, result.veris_pre_screen)

Next Steps

Authentication - understand HMAC signing for direct API calls
KYA Concepts - learn about the 4-level trust hierarchy
Setting Up Policies - configure advanced spending rules
Micropayment Channels - sub-cent payments for high-frequency workloads
Payments API Reference - full endpoint documentation