oris-kya-verify

Standalone Know-Your-Agent verifier. Reads on-chain EAS attestations and verifies EIP-712 signatures with zero Oris API dependency. Drop into any payment gateway, wallet provider, or compliance pipeline to verify the agent on the other side of a transaction.

The package implements the public KYABundle schema published at docs.useoris.xyz/spec/kya-bundle-v1.json. Any KYA attestation issued by Oris on Base, Ethereum, Arbitrum, or Optimism mainnet can be verified by this library without ever hitting an Oris service.

Why this exists

Oris issues two parallel attestations for every Know-Your-Agent state transition (promote, demote, suspend):

1. An off-chain EIP-712 signed message recoverable to the Oris MPC key.
2. An on-chain EAS attestation on Base + Ethereum (with optional replication to Arbitrum / Optimism).

A third party can verify either independently. This library wraps both checks behind a single KYAVerifier.verify() call.

Install

pip install oris-kya-verify

Dependencies: httpx, coincurve, eth-abi. No web3.py, no Postgres, no Oris SDK.

Usage

import asyncio
from oris_kya import KYAVerifier

async def main():
    verifier = KYAVerifier(chain="base")
    bundle = await verifier.verify("did:ethr:8453:0x7f3a9c2d1b4e5f6a7b8c9d0e1f2a3b4c5d6e7c2d")

    print(f"KYA level: {bundle.kya_level}")
    print(f"Risk score: {bundle.risk_score}/100")
    print(f"Status: {bundle.kya_status}")
    print(f"Attestation UID: {bundle.attestation_uid}")
    print(f"Signed by: {bundle.signer_address}")  # Should match the Oris MPC key
    print(f"Issued at: {bundle.issued_at}")
    print(f"Expires at: {bundle.expires_at}")
    print(f"Expired? {bundle.is_expired}")

    if bundle.kya_level >= 3 and not bundle.is_expired:
        # Authorize the payment.
        pass

asyncio.run(main())

Supported chains

Override rpc_url in the KYAVerifier constructor to point at your own RPC (recommended for production: Alchemy, Infura, Helius, etc.).

Error handling

The library raises typed exceptions you can catch by category:

• KYANotAttestedError — no on-chain attestation exists for this agent.
• KYAExpiredError — the latest attestation has passed its expires_at.
• KYAInvalidSignatureError — the EIP-712 signature does not recover to the expected Oris MPC signer.
• KYAVerificationError — base class for any of the above.

Network failures bubble up as httpx.HTTPError. The library never silently fails: every "yes" answer is cryptographically grounded.

Schema

The KYABundle returned by verify() is a frozen dataclass that mirrors the public JSON schema at docs.useoris.xyz/spec/kya-bundle-v1.json. Use the schema directly if you are implementing your own verifier in a different language.

License

Apache-2.0. See LICENSE.