Register an agent

This guide walks an agent from anonymous registration through the KYA ladder up to L3 Autonomous. L4 Institutional is enterprise-only and not covered here.

Goal

Register an agent, attach the evidence each KYA level demands, and open the spending envelope appropriate to the agent’s role.

Prerequisites

• An Oris developer account at useoris.xyz/oris-dev-signup.
• API key and Ed25519 signing key in environment variables.
• Python 3.10 or Node.js 20.

Step 1: Register at L0

Python

agent = client.agents.create(
    name="procurement-bot",
    description="Buys cloud compute credits for the platform team.",
    tenant="acme.eth",
)
print(agent.id, agent.kya_level)

TypeScript

const agent = await client.agents.create({
  name: 'procurement-bot',
  description: 'Buys cloud compute credits for the platform team.',
  tenant: 'acme.eth',
});
console.log(agent.id, agent.kyaLevel);

The agent exists with zero spending rights. Read-only.

Step 2: Promote to L1 with developer KYB

Python

client.agents.promote(agent.id, target_level=1, attestation="kyb_dev")

TypeScript

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

The agent can now run low-cap payments on a single chain.

Step 3: Promote to L2 with user delegation

Python

delegation = client.agents.build_delegation(
    agent_id=agent.id,
    principal_address="0xPrincipal...",
    expires_at=1_900_000_000,
)

# Sign offline with the principal's wallet
signed = principal_wallet.sign(delegation.canonical_bytes)

client.agents.promote(
    agent.id,
    target_level=2,
    attestation="user_delegation",
    attestation_payload=signed.hex(),
)

TypeScript

const delegation = await client.agents.buildDelegation({
  agentId: agent.id,
  principalAddress: '0xPrincipal...',
  expiresAt: 1_900_000_000,
});

const signed = await principalWallet.sign(delegation.canonicalBytes);

await client.agents.promote(agent.id, {
  targetLevel: 2,
  attestation: 'user_delegation',
  attestationPayload: signed.toString('hex'),
});

Multi-chain access opens. Marketplace eligibility follows.

Step 4: Wait for L3 baseline

L3 is automatic. After thirty days of clean payment activity (no drift events, no policy denials, no revocations), the engine promotes the agent. You will receive a webhook:

{
  "event": "kya.promoted",
  "agent_id": "ag_...",
  "from_level": 2,
  "to_level": 3,
  "promoted_at": "2026-06-28T..."
}

Verification

Confirm the current KYA level:

Python

a = client.agents.get(agent.id)
assert a.kya_level == 3
print(a.kya_status, a.drift_score_bp)

TypeScript

const a = await client.agents.get(agent.id);
if (a.kyaLevel !== 3) throw new Error('not yet L3');

Troubleshooting

• OrisAuthError on promote — the API key does not match the tenant that registered the agent.
• L2 promotion rejected — the delegation signature does not match the principal address on file.
• Stuck at L2 past 30 days — check the activity log for drift events. Any drift event in the last 30 days resets the L3 clock.

Where to go next

• KYA feature for the full ladder reference.
• Wallet setup to provision wallets across chains.
• Policy configuration to lock down the spending envelope.