ovynox-sdk (Python)

Python counterpart to @ovynox/sdk (TypeScript) — same API surface, same scope. See that package's README for the full picture; this one is kept short since the two are meant to stay in lockstep.

Current scope (important)

Policy/probation checking, agent/policy management, approvals, and reputation lookup are all real. wrap_payment() is an intentional NotImplementedError stub — no real x402 payment execution happens via this SDK yet.

Install

Not yet published to PyPI — for now, use directly from this monorepo (pip install -e packages/ovynox-sdk-python).

Usage

from ovynox import Ovynox

client = Ovynox(api_key=os.environ["OVYNOX_API_KEY"], base_url="http://localhost:3000")

# external_agent_id is always auto-generated (globally unique) -- nothing
# external it would ever need to match
agent = client.register_agent(name="My purchasing agent")

client.set_spend_policy(
    agent["external_agent_id"],
    max_per_transaction=25,
    approval_threshold=100,
    block_list=["x402:agent:known-bad-actor-03"],
)

# Optional: describe the agent and where it can actually be reached, so
# other agents can discover it -- served (with real reputation folded
# in) at the public GET /api/v1/agents/:external_agent_id/agent-card.json
client.set_agent_card(
    agent["external_agent_id"],
    description="Buys market-data access on behalf of my company.",
    endpoint_url="https://my-agent.example.com/a2a",
)

result = client.check_transaction(
    external_agent_id=agent["external_agent_id"],
    amount=4.5,
    counterparty_agent_id="x402:agent:some-vendor",
)

if result["status"] in ("passed", "warned"):
    ...  # execute the real x402 payment yourself
elif result["status"] == "blocked":
    raise RuntimeError("blocked by spend policy")
elif result["status"] == "pending_approval":
    ...  # wait for approval, e.g. client.approve_transaction(result["transactionId"])

Discovering agents

directory = client.list_directory(sort="trust")  # or "active"
# Every agent with a real transaction history, no API key needed.

See examples/crewai_tool.py for wrapping check_transaction as a CrewAI tool.