Official Python client for the 1Claw Vault API.
Use this SDK when you're writing Python services, cron jobs, or agent backends that talk to 1Claw directly. It covers vaults, secrets, agents, policies, the Intents API, execution bindings, billing, and the rest of the REST surface.
Agent keys (ocv_) auto-exchange for short-lived JWTs and refresh before expiry. User keys (1ck_) work the same way. You do not need to hand-roll token rotation or parse error responses from scratch.
If you're using LangChain or CrewAI, consider langchain-1claw or 1claw-crewai-tools instead. They wrap this client as framework tools. This package is the low-level building block.
Agent types include tx_approval_policy, typed_data_policy, simulation_failure_policy, raw_signing_policy, extended guardrails (tx_block_unlimited_approvals, USD caps, per-recipient limits), and auto_suspended. Matching transactions return 202awaiting_approval; approve via client.approvals.decide().
awaitclient.agents.update(agent_id, UpdateAgentRequest(
tx_approval_policy={"require_above_native": {"ethereum": "0.1"}},
typed_data_policy="approve",
tx_block_unlimited_approvals=True,
))pip install oneclawfromoneclawimportcreate_client# Agent keys (ocv_) auto-exchange for JWTs and refresh before expiryclient=create_client(api_key="ocv_your_agent_key")
# Agent ID is auto-discovered from the token exchangeprint(client.resolved_agent_id)fromoneclawimportcreate_client# User API key (1ck_) — auto-exchanges for JWTclient=create_client(api_key="1ck_your_user_key")
# Or login with email/passwordclient=create_client()
client.auth.login("user@example.com", "password")client=create_client(token="eyJ...")# Create a vaultresp=client.vaults.create("my-vault", description="Production secrets")
vault_id=resp.data["id"]
# List vaultsvaults=client.vaults.list()
forvinvaults.data["vaults"]:
print(v["name"])# Store a secretclient.secrets.set(vault_id, "api-key", "sk-secret-value")
# Retrieve a secretsecret=client.secrets.get(vault_id, "api-key")
print(secret.data["value"])
# Server-side rotation (vault generates a random value)client.secrets.rotate_generate(vault_id, "api-key", length=64, charset="base64")
# List versionsversions=client.secrets.list_versions(vault_id, "api-key")# Register an agentresp=client.agents.create("my-agent", description="CI/CD bot")
agent=resp.data["agent"]
api_key=resp.data["api_key"] # Save this — shown only once# Self-enroll (no auth required)client.agents.enroll("my-agent", "admin@example.com")# Create a delegation (human-only)client.agents.create_delegation(
orchestrator_id,
delegate_id=sub_agent_id,
allowed_tools=["delegate_task"],
max_daily_delegations=100,
delegation_mode="caller",
)
# List and query delegationsdelegations=client.agents.list_delegations(agent_id)
effective=client.agents.get_effective_delegations(agent_id)
# Revoke a delegationclient.agents.revoke_delegation(agent_id, delegation_id)# Grant an agent read access to secrets matching a patternclient.policies.create(
vault_id,
principal_type="agent",
principal_id=agent_id,
secret_path_pattern="production/*",
permissions=["read"],
)# Submit a transactionresp=client.agents.submit_transaction(
agent_id,
chain="ethereum",
to="0x...",
value="1000000000000000", # weimax_fee_per_gas="30000000000",
max_priority_fee_per_gas="1000000000",
)
print(resp.data["tx_hash"])
# Unified signing (personal_sign, typed_data, transaction)resp=client.agents.sign_intent(
agent_id,
intent_type="personal_sign",
chain="ethereum",
message="0x48656c6c6f",
)
print(resp.data["signature"])
# Non-EVM: Solana devnet native transferresp=client.agents.submit_transaction(
agent_id,
chain="solana-devnet",
to="RecipientBase58...",
value="0.001",
)
# Non-EVM: Bitcoin testnetresp=client.agents.sign_transaction(
agent_id,
chain="bitcoin-testnet",
to="tb1q...",
value="0.00001",
fee_rate_sat_per_vbyte=5,
)# Create a binding with an inline credentialresp=client.bindings.create(
agent_id,
name="httpbin",
binding_type="http",
config={"base_url": "https://httpbin.org"},
guardrails={"allowed_paths": ["/get", "/status/*"]},
credential={"token": "secret"},
)
binding_id=resp.data["id"]
# Create a binding with a vault_ref credential (live-pointer to an existing secret)resp=client.bindings.create(
agent_id,
name="stripe-api",
binding_type="http",
config={"base_url": "https://api.stripe.com"},
credential_source={
"type": "vault_ref",
"vault_id": vault_id,
"path": "integrations/stripe-key",
},
)
# List bindingsbindings=client.bindings.list(agent_id)
# Test connectivityresult=client.bindings.test(agent_id, binding_id)
# Execute an HTTP intentresp=client.bindings.execute(
agent_id,
binding="httpbin",
intent_type="http",
params={"method": "GET", "path": "/get"},
)
print(resp.data["execution_id"])
# Rotate credential (human-only)client.bindings.rotate_credential(agent_id, binding_id, credential={"token": "new-secret"})
# List execution historyevents=client.bindings.list_executions(agent_id, limit=20)
# Update guardrailsclient.bindings.update(agent_id, binding_id, guardrails={"allowed_hosts": ["httpbin.org"]})
# Delete a bindingclient.bindings.delete(agent_id, binding_id)# Provision a signing keyclient.signing_keys.create(agent_id, "ethereum")
# List keyskeys=client.signing_keys.list(agent_id)
# Check balancebalance=client.signing_keys.balance(agent_id, "ethereum")# Create a treasuryclient.treasury.create("Team Treasury", safe_address="0x...", chain="ethereum")
# Create a multisig proposalclient.treasury.propose(treasury_id, chain="ethereum", to="0x...", value="1000000000")
# Sign a proposalclient.treasury.sign_proposal(treasury_id, proposal_id, signature="0x...", decision="approve")# Generate wallets for all supported chainsclient.treasury_wallets.generate()
# Check balancebalance=client.treasury_wallets.balance("ethereum")
# Send tokens (requires password re-auth)client.treasury_wallets.send(
"ethereum",
to="0x...",
value="1000000000000000",
password="your-account-password",
)# Register a platform appresp=client.platform.create_app("My App", "my-app")
plt_key=resp.data["api_key"] # Save this# Provision a userconn=client.platform.upsert_user(email="user@example.com")
# Bootstrap resources from a templatebootstrap=client.platform.bootstrap_user(conn.data["connection_id"])
# Browse the public marketplace (no auth required)apps=client.platform.marketplace(category="finance")
# Get app stats (connections, bootstraps, grants)stats=client.platform.get_app_stats(app_id)
# Rotate webhook signing secret (returns new secret once)secret=client.platform.rotate_webhook_secret(app_id)client.webhooks.create(
url="https://example.com/webhook",
events=["agent.transaction.broadcast", "proposal.executed"],
secret="whsec_...",
)# List risk eventsevents=client.risk.list_events(severity="high")
# Register a honeytokenclient.risk.create_honeytoken(vault_id, "canary/secret-key")client=create_client(api_key="ocv_...", dpop=True)approvals=client.approvals.list(status="pending")
client.approvals.decide(approval_id, "approved")client.auth.send_email_otp("user@example.com")
resp=client.auth.verify_email_otp("user@example.com", "123456")
client.auth.social_login(provider="google", id_token="...")
# Revoke an OAuth token (RFC 7009)client.oauth_connect.revoke_token("eyJ...", token_type_hint="access_token")
# Revoke consent for a platform app (deletes consent + revokes all tokens)client.oauth_connect.revoke_consent(app_id)Note: For the full API surface (non-EVM transaction signing, spend policies, deposit destinations, fiat ramps, internal accounts, and more), see the TypeScript SDK and the OpenAPI spec.
# Create a cron-based automation (workflow_spec required)client.automations.create(
name="rotate-api-key",
agent_id=agent_id,
trigger_type="cron",
cron_expr="0 0 * * 0", # weeklytimezone="UTC",
workflow_spec={
"steps": [
{"type": "log", "action": "run_agent_task", "message": "Rotate weekly API keys"}
]
},
)
# List automations in the orgautos=client.automations.list()
# Manually triggerclient.automations.trigger(automation_id)
# Get a specific runrun=client.automations.get_run(automation_id, run_id)
# Cancel a running automation (human-only)client.automations.cancel_run(automation_id, run_id)
# Browse preset templates (public, no auth)presets=client.automations.list_presets()# Register a Telegram channel for an agent (human-only)ch=client.channels.create(agent_id, "telegram", channel_name="Support Bot")
# List channelschannels=client.channels.list(agent_id)
# Send a message via a channelclient.channels.send_message(agent_id, channel_id, content="Hello from 1Claw!")
# List message historymessages=client.channels.list_messages(agent_id, channel_id)# Store a memory entry (namespace + key)client.memory.put(agent_id, "preferences", "output_format", value="JSON")
# Get a specific entryentry=client.memory.get(agent_id, "preferences", "output_format")
# Semantic search within a namespaceresults=client.memory.search(agent_id, namespace="preferences", query="output format", top_k=5)
# List entries in a namespaceentries=client.memory.list(agent_id, "preferences")
# List all namespacesnamespaces=client.memory.list_namespaces(agent_id)
# Delete an entryclient.memory.delete(agent_id, "preferences", "output_format")
# Delete an entire namespaceclient.memory.delete_namespace(agent_id, "preferences")# Deploy a runtimeruntime=client.runtimes.create(
agent_id=agent_id,
name="my-agent-runtime",
template="python",
preset="small",
env_public={"MODEL": "gpt-4"},
shell_access_enabled=True,
)
# List runtimesruntimes=client.runtimes.list()
# Lifecycleclient.runtimes.start(runtime_id)
logs=client.runtimes.logs(runtime_id, limit=100)
client.runtimes.stop(runtime_id)
# Interactive shell (human-only, step-up password / passkey / reauth token)session=client.runtimes.create_shell_session(runtime_id, password="...")
# Connect a WebSocket client to session.data["ws_url"] with the session_token# Publish agent to directoryclient.discovery.publish(
agent_id,
description="Automated treasury management agent",
tags=["defi", "treasury", "base"],
category="finance",
)
# Search the directoryresults=client.discovery.search(query="treasury management", tags=["defi"])
# Update listingclient.discovery.update_listing(agent_id, tags=["defi", "treasury", "ethereum", "base"])fromoneclawimportcreate_client, OneclawError, AuthError, NotFoundErrorclient=create_client(api_key="ocv_...")
# Envelope-style (no exceptions)resp=client.vaults.get("nonexistent-id")
ifresp.error:
print(f"Error: {resp.error.message}")
# Exception-style (use the underlying HTTP client)try:
data=client._http.request_or_throw("GET", "/v1/vaults/bad-id")
exceptNotFoundError:
print("Vault not found")
exceptAuthError:
print("Authentication failed")
exceptOneclawErrorase:
print(f"API error: {e} (status={e.status})")withcreate_client(api_key="ocv_...") asclient:
vaults=client.vaults.list()
# Connection pool is automatically closed# Agent on-chain accounts (EOA + counterfactual Safe)accounts=client.agents.list_accounts(agent_id)
plan=client.agents.migrate_to_safe(agent_id, chain="ethereum", deprecate_eoa=True)
client.agents.deprecate_eoa_account(agent_id, "ethereum")
registry=client.agents.get_safe_module_registry("ethereum") # publicclient.agents.sync_org_safe_allowances() # owner/admin# Guardrail governanceclient.org.get_guardrail_shadow_report(since="2026-01-01T00:00:00Z")
client.org.list_guardrail_revisions()
client.agents.replay_guardrails(agent_id, draft_guardrails={"tx_max_value_eth": "0.1"})
# Human Factor Authclient.auth.get_human_factor_auth()
client.auth.set_human_factor_auth({"require_passkey": True})
client.treasury_wallets.get_auth_policy() # embedded wallet clients| Parameter | Default | Description |
|---|---|---|
base_url | https://api.1claw.xyz | API base URL |
token | None | Pre-existing JWT |
api_key | None | ocv_ (agent) or 1ck_ (user) key |
agent_id | None | Agent UUID (optional, auto-discovered) |
timeout | 30.0 | HTTP timeout in seconds |
- Python 3.9+
- httpx (only runtime dependency)
MIT