API Reference
All endpoints use the base URL https://api.useoris.xyz. Every request path begins with /api/v1/oris/. All responses return JSON.
Authentication
Oris uses Ed25519 asymmetric request signing. The server stores only your public key. Every request must include the following headers:
| Header | Description |
|---|---|
| Authorization | Your API key for identification. Format: oris_sk_live_... |
| X-Request-Signature | Ed25519 signature of the canonical request (128 hex characters) |
| X-Timestamp | Unix epoch timestamp. 30-second tolerance window. |
| X-Nonce | Unique token per request. Enforced via Redis SETNX with 30-second TTL. |
| X-Agent-ID | Agent UUID. Required for agent-scoped operations. |
Canonical signature format
{timestamp}.{nonce}.{METHOD}.{path}.{SHA256(body)}Key prefixes: oris_sk_live_ / oris_sk_test_ for API keys, oris_pk_live_ / oris_pk_test_ for Ed25519 private keys (never stored server-side).
POST/api/v1/oris/agents/register
Register a new AI agent under the authenticated developer account. The agent starts in PENDING KYA status at Level 0 and cannot transact until the KYA verification pipeline promotes it to Level 1 or higher.
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
| agent_name | string | Yes | Human-readable name for the agent |
| platform | string | Yes | Agent framework (langchain, crewai, autogen, custom) |
| agent_type | string | Yes | Classification (purchasing, trading, treasury, general) |
| declared_capabilities | string[] | Yes | List of capabilities the agent will use (payments, marketplace, micropayments) |
Response 201 Created
{
"id": "agt_8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"agent_name": "procurement-bot",
"platform": "langchain",
"agent_type": "purchasing",
"kya_status": "pending",
"kya_level": 1,
"declared_capabilities": ["payments", "marketplace"],
"created_at": "2026-04-06T10:15:22Z"
}GET/api/v1/oris/agents/{id}
Retrieve the full profile for a registered agent. Returns KYA verification status, behavioral risk score, operating chains, and anomaly count from the behavioral monitoring pipeline.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | uuid | Yes | Agent UUID returned from registration |
Response 200 OK
{
"id": "agt_8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"agent_name": "procurement-bot",
"platform": "langchain",
"agent_type": "purchasing",
"kya_status": "verified",
"kya_level": 2,
"kya_risk_score": 0.12,
"operating_chains": ["base", "arbitrum", "polygon"],
"anomaly_count": 0,
"declared_capabilities": ["payments", "marketplace"],
"created_at": "2026-04-06T10:15:22Z",
"updated_at": "2026-04-06T10:18:44Z"
}POST/api/v1/oris/payments/send
Send a stablecoin payment from an agent wallet. The request passes through the full Oris pipeline: KYA identity check, policy evaluation, balance reservation, compliance pre-screen, and on-chain submission via the configured MPC provider.
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
| agent_id | uuid | Yes | Sending agent UUID |
| recipient | string | Yes | Recipient wallet address (0x...) |
| amount | string | Yes | Payment amount in token units (e.g. "250.00") |
| stablecoin | string | Yes | Token symbol: USDC or USDT |
| chain | string | Yes | Target chain (base, arbitrum, polygon, ethereum, optimism, avalanche, bsc, celo) |
| memo | string | No | Optional payment memo for audit trail |
Response 201 Created
{
"tx_id": "tx_a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
"status": "submitted",
"chain": "base",
"amount": "250.00",
"stablecoin": "USDC",
"policy_result": "passed",
"compliance_result": "clear",
"submitted_at": "2026-04-06T10:22:08Z"
}GET/api/v1/oris/wallets
List all wallets belonging to agents under the authenticated developer account. Returns smart account addresses, balances for each stablecoin, and wallet status across all provisioned chains.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| agent_id | uuid | No | Filter by agent UUID |
| chain | string | No | Filter by chain identifier |
| status | string | No | Filter by wallet status (active, frozen, quarantined) |
Response 200 OK
{
"items": [
{
"id": "wal_d1e2f3a4-b5c6-7d8e-9f0a-1b2c3d4e5f6a",
"agent_id": "agt_8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"chain": "base",
"smart_account_address": "0x7Ff9...D4eA",
"balance_usdc": "12450.00",
"balance_usdt": "0.00",
"status": "active",
"created_at": "2026-04-06T10:16:02Z"
},
{
"id": "wal_a2b3c4d5-e6f7-8a9b-0c1d-2e3f4a5b6c7d",
"agent_id": "agt_8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"chain": "arbitrum",
"smart_account_address": "0x3aB1...92fC",
"balance_usdc": "8200.50",
"balance_usdt": "1500.00",
"status": "active",
"created_at": "2026-04-06T10:16:04Z"
}
],
"total": 2
}POST/api/v1/oris/policies
Create a spending policy for an agent. Policies are evaluated in under 10ms using Redis-cached rule sets. Each payment request is checked against all active policies before execution. Supported rule types include daily limits, per-transaction caps, recipient allowlists, and chain restrictions.
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Policy display name |
| rule_type | string | Yes | Rule type (daily_limit, per_tx_limit, recipient_allowlist, chain_restriction) |
| value | string | Yes | Rule value (e.g. "10000" for a $10,000 daily limit) |
| agent_id | uuid | Yes | Agent this policy applies to |
| is_active | boolean | No | Whether the policy is immediately active. Default: true |
Response 201 Created
{
"policy_id": "pol_c3d4e5f6-a7b8-9c0d-1e2f-3a4b5c6d7e8f",
"name": "Daily spending cap",
"rule_type": "daily_limit",
"value": "10000",
"agent_id": "agt_8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"is_active": true,
"status": "created",
"created_at": "2026-04-06T10:25:00Z"
}GET/api/v1/oris/billing/usage
Retrieve usage statistics and quota consumption for the authenticated developer account. Returns current plan details, agent and transaction quotas, and compliance screening metrics for the current billing period.
Response 200 OK
{
"plan": "developer",
"billing_period_start": "2026-04-01T00:00:00Z",
"billing_period_end": "2026-04-30T23:59:59Z",
"quotas": {
"agents": {
"used": 12,
"limit": 50
},
"transactions_monthly": {
"used": 4218,
"limit": 25000
}
},
"compliance": {
"cleared": 4196,
"blocked": 22,
"avg_latency_ms": 8.4
}
}POST/api/v1/oris/developers/provider-keys/{provider}
Save BYOK (Bring Your Own Key) credentials for an MPC provider. Oris encrypts the credentials at rest using Vault transit and uses them to sign transactions on behalf of your agents. Supported providers: turnkey, fireblocks, circle.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| provider | string | Yes | MPC provider name (turnkey, fireblocks, circle) |
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
| api_key | string | Yes | Provider API key or credential |
| org_id | string | Yes | Organization ID from the MPC provider |
Response 200 OK
{
"status": "saved",
"provider": "turnkey",
"encrypted": true,
"updated_at": "2026-04-06T10:30:15Z"
}GET/api/v1/oris/marketplace/orders
List agent-to-agent marketplace orders for the authenticated developer. Returns order details including buyer and seller agents, service description, payment amount, SLA status, and settlement state.
Query parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| status | string | No | Filter by order status (pending, active, completed, disputed) |
| limit | integer | No | Results per page. Default: 50. Max: 200. |
| offset | integer | No | Pagination offset. Default: 0. |
Response 200 OK
{
"items": [
{
"id": "ord_f1a2b3c4-d5e6-7f8a-9b0c-1d2e3f4a5b6c",
"service": "data-enrichment",
"buyer_agent": "agt_8f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"seller_agent": "agt_9e0d1c2b-3a4f-5e6d-7c8b-9a0b1c2d3e4f",
"amount": "15.00",
"stablecoin": "USDC",
"chain": "base",
"sla_met": true,
"status": "completed",
"created_at": "2026-04-06T09:45:12Z",
"settled_at": "2026-04-06T09:45:18Z"
}
],
"total": 347,
"has_more": true
}POST/api/v1/oris/micropayments/record
Record a micropayment in a payment channel. Micropayments accumulate off-chain and settle on-chain in batches. This endpoint accepts sub-cent amounts and returns the current channel balance and settlement status.
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
| agent_id | uuid | Yes | Sending agent UUID |
| recipient | string | Yes | Recipient agent or wallet address |
| amount | string | Yes | Payment amount (supports sub-cent, e.g. "0.001") |
| channel_id | string | Yes | Payment channel identifier |
Response 201 Created
{
"payment_id": "mp_b2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
"channel_id": "ch_a1b2c3d4",
"amount": "0.001",
"settled": false,
"channel_balance": "0.847",
"pending_settlement": true,
"recorded_at": "2026-04-06T10:35:22Z"
}GET/api/v1/oris/dashboard/summary
Retrieve aggregate dashboard metrics for the authenticated developer account. Returns total agent counts, wallet summaries, USDC balance across all chains, 24-hour transaction volume, and policy violation counts.
Response 200 OK
{
"total_agents": 12,
"verified_agents": 10,
"suspended_agents": 0,
"total_wallets": 28,
"total_balance_usdc": "142800.50",
"total_balance_usdt": "18200.00",
"total_transactions_24h": 892,
"total_volume_24h_usdc": "34500.00",
"policy_violations_24h": 3,
"active_policies": 24,
"operating_chains": ["base", "arbitrum", "polygon", "ethereum", "optimism"],
"updated_at": "2026-04-06T10:40:00Z"
}Additional API domains
The Oris API includes 17 router modules across the following domains. Full endpoint documentation for each domain is available in the developer docs.
| Prefix | Domain | Description |
|---|---|---|
| /api/v1/oris/developers | Developers | Developer registration, API key lifecycle, BYOK provider keys |
| /api/v1/oris/agents | Agents | Agent registration, KYA state transitions, profile updates |
| /api/v1/oris/wallets | Wallets | Wallet provisioning, balance queries, freeze and fund operations |
| /api/v1/oris/policies | Policies | Spending policy CRUD, real-time policy evaluation |
| /api/v1/oris/payments | Payments | Stablecoin payment execution and transaction history |
| /api/v1/oris/micropayments | Micropayments | Sub-cent payment channels with batched settlement |
| /api/v1/oris/marketplace | Marketplace | Agent-to-agent service listings, orders, and SLA tracking |
| /api/v1/oris/dashboard | Dashboard | Aggregate metrics, agent summaries, transaction analytics |
| /api/v1/oris/billing | Billing | Usage quotas, plan details, Stripe billing management |
| /api/v1/oris/fiat | Fiat | Fiat on-ramp and off-ramp settlement |
| /api/v1/oris/routing | Routing | Cross-chain route optimization and gas estimation |
| /api/v1/oris/webhooks | Webhooks | Webhook subscription management and delivery logs |
| /api/v1/oris/attestations | Attestations | On-chain KYA attestation issuance and verification |
| /api/v1/oris/whitelabel | White-label | Custom branding, domain configuration, embedded dashboard |
| /api/v1/oris/kya | KYA | Know Your Agent identity verification pipeline |
| /api/v1/oris/promotions | Promotions | Referral codes and promotional credit management |
| /api/v1/oris/sandbox/webhooks | Sandbox | Sandbox webhook simulation for development testing |