Skip to content

Quick Start

Get CertusOrdo running in 5 minutes.

Step 1: Install the SDK

pip install certusrodo

Step 2: Get Your API Key

If you don't have an API key yet, create an organization:

from certusrodo import CertusOrdoClient

# Create without API key to bootstrap
import httpx

response = httpx.post(
    "https://web-production-b910f.up.railway.app/v1/organizations",
    json={"name": "My Company"}
)
data = response.json()

print(f"Organization ID: {data['id']}")
print(f"API Key: {data['api_key']}")  # Save this! Only shown once.

Save Your API Key

The API key is only returned once during organization creation. Store it securely.

Step 3: Initialize the Client

from certusrodo import CertusOrdoClient

client = CertusOrdoClient(api_key="aa_your_api_key_here")

# Verify connection
health = client.health_check()
print(f"API Status: {health['status']}")  # "healthy"

Step 4: Create an Agent

# Create an agent with Ed25519 cryptographic identity
agent = client.agents.create(
    name="payment-processor",
    scopes=["payments:read", "payments:write"]
)

print(f"Agent ID: {agent.id}")
print(f"Public Key: {agent.public_key}")
print(f"Secret: {agent.secret}")  # Save this! Only shown once.

Save Your Agent Secret

The agent secret is only returned once during creation. You need it for authentication.

Step 5: Authenticate the Agent

# Exchange agent credentials for JWT tokens
tokens = client.auth.get_token(
    agent_id=agent.id,
    secret=agent.secret
)

print(f"Access Token: {tokens.access_token[:50]}...")
print(f"Expires in: {tokens.expires_in} seconds")

Step 6: Create a Transaction with Rollback

This is CertusOrdo's key differentiator:

# Begin transaction - capture state BEFORE the action
txn = client.transactions.begin(
    pre_state={
        "account_id": "ACC001",
        "balance": 1000.00
    },
    action_type="transfer_funds"
)

print(f"Transaction ID: {txn.id}")
print(f"Status: {txn.status}")  # "pending"

# ... Your agent performs the action here ...

# Option A: Commit on success
completed = client.transactions.commit(
    txn.id,
    post_state={
        "account_id": "ACC001",
        "balance": 750.00  # Balance changed
    }
)

# Option B: Rollback on failure
# rollback = client.transactions.rollback(txn.id)
# original_state = rollback.pre_state_snapshot  # Get original state back

Complete Example

Here's everything together:

from certusrodo import CertusOrdoClient

# Initialize
client = CertusOrdoClient(api_key="aa_your_api_key")

# Create agent
agent = client.agents.create(name="my-agent", scopes=["read", "write"])

# Authenticate
tokens = client.auth.get_token(agent_id=agent.id, secret=agent.secret)

# Start transaction with rollback capability
txn = client.transactions.begin(
    pre_state={"data": "original"},
    action_type="update"
)

try:
    # Your agent does work here...
    result = do_something_risky()

    # Success - commit
    client.transactions.commit(txn.id, post_state={"data": "updated"})

except Exception as e:
    # Failure - rollback
    rollback = client.transactions.rollback(txn.id, reason=str(e))
    print(f"Rolled back to: {rollback.pre_state_snapshot}")

Next Steps