# 1Claw — AI Agent Secrets Management

> HSM-backed secret management for AI agents and humans. Zero-knowledge vault with envelope encryption, agent-native access control, customer-managed encryption keys (CMEK), Intents API for transaction signing, and x402 micropayments.

## Links

- Website: https://1claw.co
- API: https://api.1claw.co
- Docs: https://docs.1claw.co
- MCP Server: https://mcp.1claw.co
- Shroud (TEE proxy): https://shroud.1claw.co
- Dashboard: https://1claw.co (login required)
- GitHub: https://github.com/1clawAI/1claw
- npm SDK: https://www.npmjs.com/package/@1claw/sdk
- npm CLI: https://www.npmjs.com/package/@1claw/cli
- npm MCP: https://www.npmjs.com/package/@1claw/mcp
- npm OpenAPI Spec: https://www.npmjs.com/package/@1claw/openapi-spec
- npm elizaOS plugin: https://www.npmjs.com/package/@1claw/plugin-elizaos
- Contact: ops@1claw.co

## What 1Claw Does

1Claw stores and manages secrets (API keys, tokens, certificates, private keys, environment variables) in HSM-backed encrypted vaults. AI agents are first-class principals — they authenticate with scoped API keys, receive short-lived JWTs, and access only the secret paths explicitly granted by a human via policies.

## Architecture

- **Vault API** (Rust/Axum) at api.1claw.co — RESTful API with JWT Bearer auth, HSM-backed signing
- **Shroud** (Rust) at shroud.1claw.co — TEE-protected LLM proxy + transaction signing (GKE, AMD SEV-SNP)
- **Dashboard** (Next.js) at 1claw.co — Web UI for humans, onboarding connect wizard (`/onboarding/connect`), setup wizards
- **MCP Server** (TypeScript) at mcp.1claw.co — Model Context Protocol for AI agents; canonical local config is stdio `npx @1claw/mcp` + `ONECLAW_AGENT_API_KEY`
- **SDK** (@1claw/sdk) — TypeScript client library
- **Wallet React** (@1claw/wallet-react v0.2.0) — Embeddable React treasury widget for Platform API apps. `<OneclawTreasuryWidget />` (Send/Swap/Receive) and `<OneclawEmbeddedWallet />` (social login + full wallet UI). `useOneclawWallet()` exposes `wallets`, `balances`, `send()`, `swap()`, `refresh()`. Social login via `POST /v1/auth/social-login`; Email OTP via `sendEmailOtp(email)` / `verifyEmailOtp(email, code, chains?)`; passkey tx auth via `tx-assert` endpoints.
- **CLI** (@1claw/cli) — Command-line tool for CI/CD and DevOps
- **elizaOS Plugin** (@1claw/plugin-elizaos) — 8 actions + context provider for elizaOS agents (vault secrets + multi-chain signing)
- **Mobile App** (Expo/React Native) — Human-in-the-loop companion for iOS + Android: approval inbox with risk tiers, agent management, passkey/biometric auth, treasury wallets, activity feed. Beta.

Both `api.1claw.co` and `shroud.1claw.co` serve the full Intents API. Shroud adds TEE-grade key isolation, LLM traffic inspection (secret redaction, PII scrubbing, prompt injection defense), and intent validation for transactions.

## Authentication

- **Human users**: Email/password (with **forgot password** flow: `POST /v1/auth/forgot-password` + `reset-password`, dashboard `/forgot-password` & `/reset-password`, CLI `1claw forgot-password` / `1claw reset-password`; **account lockout** after 10 failed attempts for 15 minutes), Google OAuth (ID token verified via JWKS), SSO (WorkOS SAML/OIDC), **WebAuthn passkeys** (passwordless login via P-256 ECDSA; register/assert ceremonies at `/v1/auth/passkeys/*`), or personal API keys (`1ck_` prefix). Password changes and resets invalidate all existing sessions. Platform-provisioned users (OIDC/Google, no password) can set their first password via `POST /v1/auth/set-password`.
- **AI agents**: Three auth methods — API key (`ocv_` prefix, default), mTLS (client certificate), or OIDC Client Credentials. API key agents exchange credentials for short-lived JWT via `POST /v1/auth/agent-token`. Supports key-only auth: agents can provide just `api_key` (without `agent_id`) and the server resolves the agent from a stored key prefix.
- **MFA**: Optional TOTP 2FA for human logins (**all tiers**, including Free). Optional **passkey login MFA** (`require_passkey_for_mfa` via `GET/PATCH /v1/auth/settings`) completes via `POST /v1/auth/mfa/passkey/begin` + `.../complete` when enabled (takes precedence over TOTP when both are configured).
- **Vault passkey unlock**: Optional per-user `require_passkey_for_vaults` — secret reads require `X-Passkey-Token` from `POST /v1/auth/passkeys/vault-assert/begin` + `complete` (5-minute reusable token). Dashboard: Settings → Security. Separate from passkey login MFA above.
- **API keys**: `1ck_` keys work as Bearer tokens on all authenticated endpoints
- **OIDC federation (1claw as IdP)**: 1claw publishes a standard OpenID Connect issuer at `https://api.1claw.co` so external relying parties (Anthropic Workload Identity Federation, GCP STS, AWS STS, etc.) can validate 1claw-issued JWTs without static API keys. Public endpoints: `GET /.well-known/openid-configuration`, `GET /.well-known/jwks.json`. RFC 8693 token exchange: `POST /v1/auth/federated-token` (accepts JSON or form-encoded; takes `grant_type=urn:ietf:params:oauth:grant-type:token-exchange`, `subject_token` (agent JWT or `ocv_` key), `subject_token_type`, `audience`; returns RS256 JWT signed by an HSM-backed RSA-2048 KMS key). Two KMS signing keys: existing `EC_SIGN_ED25519` for agent JWTs and new `RSA_SIGN_PKCS1_2048_SHA256` for federation tokens. Both publish every active version under a deterministic `kid` (`eddsa-vN`, `rs256-vN`). Agent fields: `federation_enabled` (default false — zero-trust), `federation_audiences` (TEXT[] allowlist; empty = deny all), `federated_token_ttl_seconds` (default 900s, hard cap 3600s).
- **Email OTP (passwordless)**: `POST /v1/auth/email-otp/send` sends a 6-digit code to the user's email (5-min TTL). `POST /v1/auth/email-otp/verify` verifies the code and returns a JWT, auto-provisioning treasury wallets for embedded wallet flows. Supports `platform_app_id` for platform-scoped logins.
- **OAuth2 authorization server ("Sign in with 1Claw")**: 1Claw acts as an OAuth2/OIDC authorization server. `GET/POST /v1/oauth/authorize` (consent + code issuance, PKCE S256 required), `POST /v1/oauth/token` (code → access_token + RS256 id_token), `GET /v1/oauth/userinfo` (sub, email, name, wallet_address). Dashboard consent page at `/oauth/authorize`.

## Core Concepts

**Onboarding golden path (v0.59.2):** `GET /v1/org/onboarding/status` (human JWT) tracks welcome bundle progress. `POST /v1/onboarding/provision` creates `default` vault, `examples/hello`, MCP agent, and `**` read/write policy; returns one-time `ocv_` key plus `mcp_stdio_config` for stdio MCP. Signup hooks async-provision the welcome bundle. `1claw setup` calls provision then configures Cursor/Claude/VS Code. Dashboard: `/onboarding/connect`. SDK: `client.org.getOnboardingStatus()`, `.provisionOnboarding()`. Python: `client.org.get_onboarding_status()`, `.provision_onboarding()`. Prod test: `scripts/test-onboarding-prod.sh`.

### Vaults
Isolated containers for secrets. Each vault has its own HSM key encryption key (KEK). Secrets within a vault are envelope-encrypted: per-secret data encryption keys (DEKs) wrapped by the vault KEK.

### Secrets
Key-value pairs stored in vaults, addressed by path (e.g., `api-keys/stripe`). Paths are validated server-side (no `..`, no zero-width/confusable bypass; list prefixes validated). Supports types: generic, password, api_key, certificate, private_key, ssh_key, env. Secrets are versioned. Optional metadata, expiry, and max access count.

### Environment Variables (v0.51)
First-class per-key env vars on vaults with Vercel-style environment scoping. Per-vault `env_vars` table stores individual encrypted entries (`DATABASE_URL`, `STRIPE_KEY`, etc.) targeting specific environments (production, preview, development, custom). Org-level shared vars (`org_env_vars`) linked to multiple vaults; vault-level vars with the same key+environment always win. Branch overrides for preview/feature-branch deployments. Sensitive write-only mode (values non-readable after creation for humans; disallowed on Development-only; org setting `env.require_sensitive_prod` forces prod/preview vars sensitive). Resolution endpoint `GET /v1/vaults/{id}/env-vars/resolve?environment=preview&git_branch=feat/x` returns the final KEY=VALUE set with three-tier precedence: shared < vault < branch override. Cloud Runtime injection merges resolved env vars into the container environment at start/rebuild (64KB combined limit; restart required). Vault endpoints: `GET/POST /v1/vaults/{id}/env-vars`, `GET/PATCH/DELETE /v1/vaults/{id}/env-vars/{key}`, `GET/POST /v1/vaults/{id}/environments`, `DELETE /v1/vaults/{id}/environments/{slug}`. Org endpoints: `GET/POST /v1/org/env-vars`, `PATCH /v1/org/env-vars/{key}`, `DELETE /v1/org/env-vars/{id}`, `POST /v1/org/env-vars/{id}/link`, `DELETE /v1/org/env-vars/{id}/links/{vault_id}`. SDK: `client.envVars.list()`, `.create()`, `.get()`, `.update()`, `.delete()`, `.resolve()`. MCP: `resolve_env` tool. CLI: `env ls`, `env add`, `env rm`, `env environments ls|add|rm`, `-e` flag on `pull`/`push`/`run`. Dashboard: Env Variables tab on vault detail, Shared Env Vars in org settings, environment management dialog. Guide: https://docs.1claw.co/docs/guides/environment-variables

### Agent Environment Tagging (v0.52)
Agents can be tagged with a named environment (`production`, `preview`, `development`, or custom) for policy scoping and env var resolution. Fields on `agents`: `environment`, `environment_locked` (immutable after bootstrap), `env_auto_resolve` (resolve endpoint auto-fills from agent tag), `per_environment_guardrails` (JSONB overrides per environment). JWT includes `environment` claim when set. Policy conditions support `environment_in` array for environment-scoped access. When `env_auto_resolve` is true, `GET /v1/vaults/{id}/env-vars/resolve` omits the `environment` query param and uses the agent's tag. Org setting `env.enforce_agent_environment_scope` blocks agents from resolving vars outside their tagged environment. CLI: `--environment`, `--environment-locked`, `--env-auto-resolve` on `agent create`; `--environment`, `--environment-locked`, `--env-auto-resolve`, `--per-environment-guardrails` on `agent update`. Dashboard: environment tag selector on agent create/detail pages. Migration 201. Guide: https://docs.1claw.co/docs/guides/agent-environment-tagging

### Guardrail Governance & HFA (v0.56)
**Guardrail governance:** Convention 6 execution guardrail shadow mode (`enforcement: log|enforce`); audit `guardrail_shadow.would_deny`; `GET /v1/org/guardrail-shadow-report`, `GET /v1/org/guardrail-revisions`, `POST /v1/agents/{id}/guardrails/replay` (dry-run against recent txs). Dashboard: Settings → Security → Guardrails tab. CLI: `1claw guardrails shadow-report|revisions|replay`. SDK: `client.org.getGuardrailShadowReport()`, `.listGuardrailRevisions()`, `client.agents.replayGuardrails()`. MCP: guardrail governance tools.
**Address screening:** Per-agent `address_screening_policy` JSON (`mode`: `off`|`deny`|`approve`) screens transaction recipients at signing time. CLI: `--address-screening-policy` on `agent create|update`.
**Human Factor Auth (HFA):** Treasury wallet send/swap/export require password or passkey per configurable policy. Resolution: user `human_factor_auth_policies` → `wallet_spend_policies.human_factor_auth` → defaults. Endpoints: `GET/PUT /v1/auth/human-factor-auth`. Spend policies accept optional `human_factor_auth` JSON. Webhooks: `human_factor_auth.denied`, `human_factor_auth.satisfied`, `guardrail_shadow.would_deny`. Dashboard: Settings → Security → Wallet human factor auth card. v0.56.2 adds swap passkey digests and passkey-only send/swap in dashboard + wallet-react.
**Guardrail widening (v0.56.2):** Binding/agent guardrail edits that widen access queue behind `policy_change` approval with step-up re-auth (`X-Auth-Confirm`); PATCH returns **202** with `pending_approval_id` until approved. Narrowing edits apply immediately.
**Safe foundation (v0.56.2, Phase 5):** Counterfactual Safe provisioning — `GET/POST /v1/agents/{id}/accounts`, `POST .../accounts/migrate`, `POST .../accounts/{chain}/deprecate-eoa`, `GET /v1/safe/module-registry/{chain}`, `POST /v1/org/safe/sync-allowances`. On-chain deploy/cosign/passkey/timelock/4337 stubs return 501 pending Guard audit. CLI: `1claw agent accounts list|migrate|deprecate-eoa`, `1claw safe module-registry|sync-allowances`. MCP: `list_agent_accounts`, `migrate_agent_to_safe`, `deprecate_agent_eoa`, `get_safe_module_registry`, `sync_org_safe_allowances`. Dashboard: Safe migration wizard at `/agents/[agentId]/migrate-safe`.
**Gas & execution guardrails (v0.56.3):** Per-chain `gas_daily_budget_native` in `per_chain_guardrails` — UTC-day cumulative EVM gas spend (`agent_gas_ledger`, migration 213). Binding guardrail `inject_idempotency_key: true` injects deterministic outbound `Idempotency-Key` on HTTP/GraphQL execute (SHA-256 hex of binding id, method, path, body).

### Agents
AI agent identities registered via the dashboard or API. Agents support three authentication methods: `api_key` (default, generates `ocv_` prefixed key), `mtls` (client certificate fingerprint), and `oidc_client_credentials` (OIDC issuer + client ID). All agents automatically receive an Ed25519 SSH keypair stored in a dedicated `__agent-keys` vault for future encrypted A2A messaging. Agents can be scoped to specific vaults (`vault_ids`), specific secret paths (via policies), and have a custom token TTL (`token_ttl_seconds`). Agents cannot access anything not explicitly granted by a human.

### Agent Self-Enrollment
Agents can register themselves with zero credentials via `POST /v1/agents/enroll` (public endpoint). The agent provides its name and the email of a human with a 1Claw account. The API creates the agent and emails credentials to the human. Available via SDK (`AgentsResource.enroll()`), CLI (`1claw agent enroll`), and raw HTTP. Rate limited: 1 per email per 10 minutes + IP rate limiting. Zero access by default until the human creates policies.

### Agent-to-Human Sharing
Agents can share secrets back with the human who created them using `recipient_type: "creator"`. No email or user ID needed — the API resolves it from the agent's `created_by` field. The human sees the share in their Inbound tab and accepts it. This enables a pattern where agents autonomously discover/generate credentials and report them to their human.

### Policies
Access control rules that bind a principal (agent or user) to a set of secret paths in a vault. Policies specify path patterns (glob), permissions (read/write), optional conditions (IP ranges, time windows), and expiry. **Policy Engine v2 (v0.47):** Policies now support `effect` ("allow" or "deny"), `priority` (integer, higher wins), and `attribute_conditions` (JSONB) for fine-grained evaluation with deny rules. **Agent token auto-revocation:** When an access policy targeting an agent is created, updated, or deleted, all of that agent's active JWTs are automatically revoked (via the `agent_active_tokens` table). The agent must re-exchange credentials to obtain a fresh token with updated scopes.

### Cedar Policies (v0.47, Team+ tier)
Declarative authorization using the Cedar policy language. Endpoints: `POST/GET /v1/org/cedar-policies` (CRUD), `GET/DELETE /v1/org/cedar-policies/{id}`, `POST /v1/org/cedar-policies/test` (dry-run evaluation with principal, action, resource, context). SDK: `client.cedarPolicies.*`. CLI: `1claw cedar-policy create|list|get|delete|test`. MCP: `list_cedar_policies`, `test_cedar_policy`.

### OPA Policies (v0.47, Business+ tier)
Open Policy Agent (OPA) Rego-based policy evaluation with custom data documents. Endpoints: `POST/GET /v1/org/opa-policies` (CRUD), `GET/DELETE /v1/org/opa-policies/{id}`, `POST /v1/org/opa-policies/test` (dry-run with input document). SDK: `client.opaPolicies.*`. CLI: `1claw opa-policy create|list|get|delete|test`. MCP: `list_opa_policies`, `test_opa_policy`.

### Sub-Organizations (v0.47)
Hierarchical organization management. Sub-orgs can inherit or independently manage billing. Endpoints: `POST/GET /v1/org/sub-orgs` (create, list), `GET/DELETE /v1/org/sub-orgs/{id}` (get, archive), `POST/DELETE /v1/org/sub-orgs/{id}/permissions` (grant, revoke), `POST /v1/org/sub-orgs/{id}/users` (add user), `POST /v1/org/sub-orgs/{id}/wallets/generate` (generate wallets). Platform API: `create_sub_org: bool` on `upsert_user`. SDK: `client.subOrgs.*`. CLI: `1claw sub-org create|list|get|archive|grant|revoke|add-user|wallets`. MCP: `list_sub_orgs`, `create_sub_org`.

### Portfolio (v0.47)
Unified balance aggregator across all wallet types (treasury wallets, signing keys, smart accounts). `GET /v1/portfolio` with optional `?chains=ethereum,solana&include_tokens=true`. Returns per-wallet balances with USD estimates. SDK: `client.portfolio.get()`. CLI: `1claw portfolio`. MCP: `get_portfolio`.

### Customer-Managed Encryption Keys (CMEK)
Enterprise opt-in feature. The human generates a 256-bit AES key in the dashboard (WebCrypto). The key never leaves their device — only its SHA-256 fingerprint is stored on the server. Secrets are encrypted client-side before upload. Server-assisted rotation re-encrypts all secrets in batches of 100 with progress tracking.

### Multi-Party Computation (MPC) Secret Storage
Vault-level opt-in. Splits secret DEKs across multiple HSM providers so no single provider holds the complete key. Three custody modes: `2of2_client_custody` (XOR split, one share returned to client), `2of3_multi_hsm` (Shamir 2-of-3 across GCP/AWS/Azure HSMs), `2of3_client_custody` (Shamir 2-of-3 with one client-held share). Enable via `POST /v1/vaults/{id}/mpc`. Client-custody modes return `client_share` on secret creation and require `X-Client-Share` header on read.

### Intents API
Agents can sign and broadcast EVM and non-EVM transactions without seeing private keys. Keys stay in the HSM. Per-agent **hard guardrails**: allowed chains, recipient allowlists, per-tx value caps, daily spending limits. **Graduated HITL (v0.54–0.55):** `tx_approval_policy` JSON routes matching txs to **202** `awaiting_approval`; `typed_data_policy` / `simulation_failure_policy` / `raw_signing_policy` escalate EIP-712, simulation failures, and raw digest signing to HITL or deny. Extended guardrails (v0.55): unlimited ERC-20 approval blocking, per-recipient limits, USD caps, `allow_erc4337`, `allow_eip7702`, in-flight daily budget holds. Circuit breaker may set `auto_suspended`; org emergency freeze via `POST /v1/org/freeze`. **29 supported EVM mainnets** (all with dRPC managed RPC when `DRPC_API_KEY` is configured): Ethereum, Base, Optimism, Arbitrum One, Polygon, Avalanche C-Chain, BNB Smart Chain, zkSync Era, Linea, Scroll, Mantle, Blast, Gnosis, Fantom, Celo, Aurora, Metis, Moonbeam, Cronos, Sonic, World Chain, Polygon zkEVM, Sei, Kaia, Mode, Arbitrum Nova, Berachain, Taiko, Zora, and Robinhood Chain (chain ID 4663). **EVM testnets:** Sepolia, Base Sepolia, Holesky, Optimism Sepolia, Arbitrum Sepolia, Polygon Amoy, Arc Testnet (stablecoin-native L2, chain ID 5042002), and Robinhood Testnet (chain ID 46630). **Non-EVM chains:** Bitcoin (via official `rust-bitcoin` crate — P2PKH, P2SH, P2WPKH, P2WSH, P2TR recipient support), Solana (via official `solana-sdk` crate — native PDA derivation, SPL token transfers), XRP, Cardano, Tron. **XRP supports 30+ transaction types** (Payment, TrustSet, OfferCreate, NFTokenMint, AMMCreate, EscrowCreate, etc.) via the `xrpl_tx_json` field — pass a raw XRPL transaction JSON object and the server uses the xrpl-rust binary codec to encode and sign it; `Account`, `Sequence`, `Fee`, `LastLedgerSequence`, and `SigningPubKey` are auto-filled when absent. **Non-EVM testnets and faucets:**
| Chain | Testnet chain value | Faucet |
| --- | --- | --- |
| Bitcoin | `bitcoin-signet` | [faucet.coinbin.org](https://faucet.coinbin.org/) |
| Solana | `solana-devnet` | [faucet.solana.com](https://faucet.solana.com/) or `solana airdrop` CLI |
| XRP | `xrp-testnet` | [xrpl.org faucets](https://xrpl.org/resources/dev-tools/xrp-faucets) |
| Cardano | `cardano-preprod` | [Cardano faucet](https://faucet.preprod.world.dev.cardano.org/basic-faucet) (also API: `curl -X POST "https://faucet.preprod.world.dev.cardano.org/send-money/<ADDR>?api_key=ooseiteiquo7Wie9oochooyiequi4ooc"`) |
| Tron | `tron-shasta` | [shasta.tronex.io](https://shasta.tronex.io/join/getJoinPage) (2,000 TRX) |

Bitcoin testnet/signet uses `tb1q…` addresses. Cardano preprod uses `addr_test1…`. Solana, XRP, and Tron use the same address on all networks. Cardano broadcast requires `BLOCKFROST_PROJECT_ID` env var (free: 50k req/day at blockfrost.io).

**TEE Enforcement (Pro+):** Two agent-level flags lock down signing/execution to hardware enclave only: `intents_require_tee` (rejects transaction/sign requests not routed through `shroud.1claw.co` — direct Vault calls get 403) and `execution_require_tee` (rejects execute requests not routed through Shroud, AND blocks all direct secret reads by the agent — forces use of Execution Intents bindings). Both require the base flag (`intents_api_enabled` / `execution_intents_enabled`) to be enabled first. Verification uses HMAC-SHA256 `X-1Claw-TEE-Origin` header set by Shroud (shared `ONECLAW_TEE_ORIGIN_SECRET`). SDK/CLI: `intents_require_tee`, `execution_require_tee` on create/update agent.

**Overhead Budget and Transaction Count Limits (v0.41.2):** Three new guardrails protect against non-value drain attacks (ATA rent drain, XRP reserve exhaustion, Tron energy drain, transaction fee storms):
- `tx_max_per_day` (INTEGER): Daily transaction count cap (UTC calendar day). Prevents high-frequency attacks.
- `tx_overhead_budget` (JSONB): Per-chain daily budget for non-value costs (rent, fees, energy) in native units. E.g. `{"solana": "0.5", "xrp": "100", "ethereum": "0.01"}`.
- `solana_ata_allowlist` (TEXT[]): Restricts which wallet addresses may have ATAs created. Prevents ATA rent drain.
- Per-chain variants: `per_chain_guardrails` supports `max_per_day`, `overhead_budget`, and `max_ata_creates_per_day`.
- Response fields: `tx_count_today`, `tx_overhead_today_by_chain` returned in `GET /v1/agents/{id}`.

**`GET /v1/agents/{id}`** returns **`tx_spent_today`** (UTC-day spend in native major units), **`tx_spent_today_by_chain`** (per-chain daily spend, e.g. `{ "ethereum": "0.5", "solana": "2.0", "bitcoin": "0.001" }`), **`tx_count_today`** (today's transaction count), and **`tx_overhead_today_by_chain`** (per-chain overhead spend) so **Shroud** and other clients enforce the same caps as the Vault API. (`tx_spent_today_eth` is a deprecated alias.) Supports EIP-155 legacy and EIP-1559 Type 2 transactions. **Gasless transactions**: set `gasless: true` on `SubmitTransactionRequest` to sponsor gas via Pimlico paymaster (ERC-4337). Optional Tenderly simulation before signing. Replay protection via `Idempotency-Key` header (UUID, 24h TTL; auto-generated by SDK and MCP). Server-side nonce serialization with an atomic `nonce_tracker` table (`SELECT FOR UPDATE`) prevents nonce collisions across concurrent agents. `GET .../transactions/{tx_id}` redacts `signed_tx` by default; pass `?include_signed_tx=true` to include it.

### Multi-Chain Signing Keys (v0.18)
Agents can have per-chain signing keys for 6 supported blockchains: Ethereum (secp256k1), Bitcoin (secp256k1), Solana (Ed25519), XRP (Ed25519, 31 supported types via `xrpl_tx_json`; SetRegularKey/SignerListSet/AccountSet/AccountDelete require explicit `xrpl_allowed_tx_types`), Cardano (Ed25519), Tron (secp256k1). Keys are provisioned by humans via `POST /v1/agents/{id}/signing-keys` with `{ chain }`. Private keys are stored in the HSM-backed `__agent-keys` vault; public keys and addresses are returned to the caller. Agents cannot provision or rotate their own keys (human-only, 403). Key lifecycle: create, list, rotate, deactivate, **export**, **import**. **Signing key export**: `POST /v1/agents/{id}/signing-keys/{chain}/export` — human-only, requires password re-authentication via `X-Auth-Confirm` header; returns `{ private_key, public_key, address, curve, chain }`; failed re-auth triggers account lockout; audit-logged. **Signing key import (v0.47, BYOK)**: `POST /v1/agents/{id}/signing-keys/{chain}/import` — human-only, requires `X-Auth-Confirm`; accepts `{ private_key, format?: "hex"|"base64"|"wif" }`. SDK: `client.signingKeys.create(agentId, { chain })`, `.list()`, `.rotate()`, `.deactivate()`, `.export(agentId, chain, { password })`, `.importKey(agentId, chain, body, password)`. CLI: `1claw agent signing-keys list`, `1claw agent signing-keys create --chain ethereum`, `1claw agent keys import`. MCP tools: `list_signing_keys`, `provision_signing_key`, `import_signing_key`.

### Extended Signing Intents (v0.18)
Unified `POST /v1/agents/{id}/sign` endpoint with `intent_type` dispatch:
- **`personal_sign`** (EIP-191): Sign a hex-encoded message. Requires `message_signing_enabled` on the agent. Returns `signature` + `message_hash` + `from`.
- **`typed_data`** (EIP-712): Sign structured typed data. Accepts full EIP-712 JSON (types, primaryType, domain, message). Returns `signature` + `typed_data_hash` + `from`. **Guardrails**: deny-by-default (`eip712_default_policy`); known dangerous types (Permit, Permit2, etc.) always require explicit allowlist; `eip712_domain_allowlist` checked by verifying contract address.
- **`transaction`**: Sign EIP-2718 typed transactions (types 0–4): legacy, EIP-2930 access list, EIP-1559, EIP-4844 blob, EIP-7702 set code. Returns `signed_tx` + `tx_hash` + `from` + `tx_type`.
- **`eip712_digest`** (alias `digest`): Sign a client-computed 32-byte `hash` directly (raw/blind signing) → 65-byte `r‖s‖v` signature. For ERC-1271/ERC-7739 nested EIP-712 flows (e.g. Polymarket) where the canonical hash is computed client-side. Gated behind per-agent `raw_signing_enabled` (off by default; human-set only; bypasses guardrails; audit-logged as `signing_key.raw_digest_sign`).
MCP tools: `sign_message` (EIP-191), `sign_typed_data` (EIP-712), `sign_digest` (raw digest). SDK: `client.agents.signIntent(agentId, { intent_type, chain, ... })`.

### Bankr Dynamic Key Vending
Partner-key secret engine for short-lived Bankr wallet API keys — **preferred over static `put_secret` for Bankr credentials**. Store `bk_ptr_` server-side (`BANKR_PARTNER_KEY`); Vault issues scoped TTL-bound `bk_usr_` keys. **Deny-by-default:** agents need policy on `agents/{id}/bankr/*` in `__agent-keys`; agent lease responses omit `api_key` (Shroud resolves); MCP `lease_bankr_key` never returns the key in tool output. Recommend TTL 5–15 min; agent default 15 min; max 24h. Endpoints: `POST/GET/DELETE /v1/agents/{id}/bankr-keys/*`. SDK/CLI/MCP as above. Guide: https://docs.1claw.co/docs/agents/bankr-keys

### Payment Card Vault (x402 Card Ordering — Laso)
Agents can order prepaid and gift cards through 1Claw and never see the card number (PAN) or CVV by default. Ordering is paid with an **outbound x402 payment** the Vault constructs and signs using the agent's own Ethereum signing key (`agents/{id}/chains/ethereum/private_key`), which must hold USDC on Base. **PCI posture — reference mode:** for Laso cards only the Laso `card_id` and an encrypted Laso refresh token are stored; PAN/CVV are fetched just-in-time from Laso at reveal and never persisted. Manually imported cards use full encrypted storage (CVV honors one-time-read / 410-Gone semantics).

- **Ordering guardrails (per-agent, human-set):** `cards_enabled`, `card_max_order_usd`, `card_daily_limit_usd` (enforced atomically over a rolling 24h window), `card_payto_allowlist` (allowed x402 recipients; empty = built-in Laso Base recipients), `card_reveal_enabled` (whether agents may reveal subject to per-card policy), **`card_require_approval`** (default **true** — when on, orders return **202** with `status: awaiting_approval` until a human approves). Available on all tiers. Free tier defaults: $25/order, $25/day, 5 cards/month. Pro: 50/mo. Team: 200/mo. Business/Enterprise: unlimited. A **3% platform fee** per order is debited from prepaid credits (best-effort). These bound the **purchase**, not how a revealed card is later spent.
- **Human-in-the-loop approval:** When `card_require_approval` is true, `POST /v1/agents/{id}/cards/order` creates a pending approval (`action: card_order`) and a card row in `awaiting_approval` — **no x402 payment until approved**. Humans can approve via **dashboard** (`/approvals`), **mobile app** (push + risk-tier step-up), or **email one-click** (`GET /v1/approvals/quick-decide?token=...&decision=approved|rejected`, proxied at `https://1claw.co/api/approvals/quick-decide`). Risk tiers: T1 (≤$25), T2 ($25–$100, biometric/re-auth), T3 (>$100, TOTP + slide). Rejecting marks the card `rejected`. Webhooks: `approval.created`, `approval.decided`, `card.rejected`.
- **x402 client validation** (the payment security boundary): before signing an EIP-3009 `TransferWithAuthorization`, the Vault validates the 402 challenge — `payTo` in the allowlist, `network == eip155:8453` (Base), `maxAmountRequired` equals the requested USDC amount, and `asset` equals the pinned Base USDC contract (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`). The stored Laso bearer token may only ever reach a hardcoded card-endpoint path allowlist — never `/withdraw` or `/send-payment`.
- **Order pipeline:** `POST /v1/agents/{id}/cards/order` (`{ kind, amount_usd, laso_server_id?, country? }`, **`Idempotency-Key` required**) returns **202** with `awaiting_approval` when `card_require_approval` is true, or journals payment immediately when false. On approval, x402 payment runs and status becomes `pending`; `card_monitor` (15s, advisory-lock leader election) polls Laso, fills `last4`/expiry/balance, stores gift-card redemption payloads as `gift_card` secrets, fires webhooks, auto-voids past `void_after`, and flags `ordering`-stuck rows as `orphaned_payment` for reconciliation.
- **Reveal (hybrid access):** `POST /v1/cards/{id}/reveal` — humans re-authenticate with `X-Auth-Confirm` (account password, **`rat_` re-auth token** from `POST /v1/auth/reauth/begin` + `complete` with method `password`, `passkey`, or **`totp`**; social-login users without a password should set up passkey/TOTP at `/settings/security`); agents get 403 unless a human enabled a per-card `reveal_policy` (single-use, TTL, audit-logged). Every reveal is audit-logged and returns a **post-reveal disclaimer**.
- **Lifecycle:** `GET /v1/cards`, `GET /v1/cards/{id}` (always masked to last4), `PATCH /v1/cards/{id}` (human-only reveal policy + `void_after`), `POST /v1/cards/{id}/void`, `POST /v1/cards/{id}/refresh`, `POST /v1/cards/import`. Webhook events: `card.ordered`, `card.ready`, `card.revealed`, `card.voided`, `card.depleted`, `card.orphaned_payment`, **`card.rejected`**, **`approval.created`**, **`approval.decided`**.
- **DB:** migrations 135–136 (`payment_cards`, guardrails); **migration 139** (`card_require_approval`, `approval_quick_tokens`, `awaiting_approval`/`rejected` statuses).
- **Shroud PAN protection:** Shroud's PII detector Luhn-validates 13–19 digit spans and detects CVV/expiry patterns, blocking PANs/CVVs in LLM traffic. Full-mode PAN secrets are excluded from the admin secrets manifest (kept out of Shroud's redaction automata to avoid expanding PCI scope).
- **SDK:** `client.cards.order()`, `.list()`, `.get()`, `.reveal({ password })`, `.update()`, `.void()`, `.refresh()`, `.import()`, `.searchGiftCards()`. **CLI:** `1claw card order|list|get|reveal|void|refresh|import`. **MCP:** `order_card`, `order_gift_card`, `search_gift_cards`, `list_cards`, `get_card_status` (reveal intentionally omitted from MCP to avoid context-window PAN exposure). **Dashboard:** Cards page (masked list, reveal dialog with password re-auth + disclaimer) and a "Card Ordering Guardrails" card on agent detail.

### Treasury
Treasury Safe multisigs and native multi-chain wallets for human users. Smart account deployment: ERC-4337 Safe 1.4.1 via permissionless.js + Pimlico. Access request flow: agents request access, humans approve/deny. Routes: `POST/GET /v1/treasury`, `GET/PATCH/DELETE /v1/treasury/{id}` (create requires `safe_address`), signers and access-request sub-routes; list access requests returns `requests[]`. Dashboard: `/treasury` (available on all tiers; wallets count toward wallet quota) and per-treasury detail (`/treasury/[id]`) with native wallet card, safe list, deploy smart account, access requests.

### Treasury Wallets (Native Multi-Chain)
HSM-backed wallet generation for human users. Supported chains: Ethereum (secp256k1), Bitcoin (secp256k1), Solana (Ed25519), XRP (Ed25519), Cardano (Ed25519), Tron (secp256k1). Available on all tiers (counts toward wallet quota). Human-only access (agents get 403). Private keys stored in a per-org `__treasury-keys` vault with MPC custody auto-configured per billing tier (XOR 2-of-2 for Pro/Team, Shamir 2-of-3 multi-HSM for Business/Enterprise). Direct API reads from `__treasury-keys` (and `__agent-keys`) are blocked with 403 — private keys are only accessible through designated export endpoints. Endpoints: `POST /v1/treasury/wallets/generate` (generate wallets for specified or all chains), `GET /v1/treasury/wallets` (list), `GET /v1/treasury/wallets/{chain}` (get by chain), `POST /v1/treasury/wallets/{chain}/export` (export with private key — **requires password re-authentication** via `X-Auth-Confirm` header; audit-logged), `POST /v1/treasury/wallets/{chain}/rotate` (rotate keypair), `DELETE /v1/treasury/wallets/{chain}` (deactivate). **Wallet import (v0.47, BYOK):** `POST /v1/treasury/wallets/{chain}/import` — import existing private key as a treasury wallet; human-only, requires `X-Auth-Confirm`; accepts `{ private_key, format?: "hex"|"base64"|"wif" }`. **Multi-chain send (v0.47):** `POST /v1/treasury/wallets/{chain}/send` now supports all 6 chains (Ethereum, Bitcoin, Solana, XRP, Cardano, Tron). Non-EVM sends accept chain-specific fields: `token_mint`, `memo`, `destination_tag` (XRP), `fee_rate_sat_per_vbyte` (Bitcoin), `xrpl_tx_json` (raw XRPL transaction), `fee_limit_sun` (Tron), `token_decimals`, `ttl` (Cardano). Swap (`POST .../swap`) remains EVM-only. **Gasless sends:** `POST /v1/treasury/wallets/{chain}/send` accepts `gasless: true` to wrap the send as an ERC-4337 UserOperation with Pimlico paymaster sponsorship (response includes `user_op_hash`; requires `PIMLICO_API_KEY`). Dashboard: `WalletChainCard` shows inline balance (30s auto-refresh), Send dialog (with gasless option), and Swap dialog per chain. Wizard UI with QR codes and key export.

### Smart Account Import (v0.47)
`POST /v1/agents/{id}/smart-accounts/import` — Import an existing Gnosis Safe smart account. Accepts `{ chain, chain_id, safe_address, verify?: bool }`. When `verify` is true (default), verifies on-chain Safe ownership before importing. SDK: `client.agents.importSmartAccount()`. CLI: `1claw agent smart-account-import`. MCP: `import_smart_account`.

### Wallet Spend Policies
Per-app and per-user spend policies for embedded wallet sends/swaps. Platform developers create app-level defaults; per-user overrides for connected users. Policy fields: `to_allowlist`, `to_denylist`, `max_value_per_tx_eth`, `daily_limit_eth`, `allowed_chains`, `allowed_tokens`, `max_transactions_per_day`, plus **inference budget** fields (v0.57): `inference_allowance_usd`, `inference_reserved_pct`, `inference_hard_stop`, `max_request_cost_usd`. Endpoints: `POST/GET /v1/platform/apps/{id}/spend-policies` (create/list), `PUT /v1/platform/connections/{id}/spend-policy` (per-user override), `GET /v1/treasury/wallets/spend-policy` (effective policy), `GET /v1/treasury/wallets/inference-budget` (connected-user inference spend vs allowance), `DELETE /v1/platform/apps/{id}/spend-policies/{pid}` (deactivate). Enforcement: `validate_wallet_send()` in treasury wallet send/swap handlers; Shroud enforces inference budgets on LLM proxy when org/platform spend policy sets allowances. DB: `wallet_spend_policies`, `wallet_send_ledger` (migration 115), inference spend tracking (migration 215).

### Treasury Proposals & Delegations
Full multisig propose/confirm/execute pipeline for Safe treasury transactions. Agents or users create proposals; signers approve or reject; auto-execute fires when the Safe threshold is met.

**Delegation model:** Two human-configurable signing modes per agent (`agents.treasury_signing_mode`):
- **Owner mode** — Agent's EOA is added as an on-chain Safe signer. Agent signs UserOps with its own key; Safe threshold is enforced.
- **Delegated mode** — Agent signs using the treasury wallet key through the Intents API. The key never leaves the `__treasury-keys` vault.

Per-delegation guardrails (spend caps, allowlists) override or intersect with agent-level guardrails — strictest wins. **Auto-approve rules** (`treasury_delegations.auto_approve_rules` JSONB): array of `{ max_value_eth, to_allowlist, auto: true }` — when a proposal matches a rule, the agent's signature is auto-inserted; if the auto-sig meets threshold, auto-execute fires immediately.

**Endpoints:**
- `POST /v1/treasury/{id}/proposals` — Create a proposal (agent or user; agent must have delegation)
- `GET /v1/treasury/{id}/proposals` — List proposals (filterable by `?status=`)
- `GET /v1/treasury/{id}/proposals/{pid}` — Get proposal with collected signatures
- `POST /v1/treasury/{id}/proposals/{pid}/sign` — Submit EIP-712 signature (approve/reject); auto-executes if threshold met
- `POST /v1/treasury/{id}/proposals/{pid}/execute` — Force-execute if threshold met (user-only)
- `DELETE /v1/treasury/{id}/proposals/{pid}` — Cancel pending proposal (proposer only)

**Auto-execute logic:** When approve signatures reach threshold: signatures collected sorted by address (Safe requirement), `execTransaction` calldata built via `crypto/safe_exec.rs` (Gnosis Safe calldata builder), broadcast via RPC, proposal updated to `executed`.

**SDK:** `TreasuryResource` — `propose()`, `listProposals()`, `getProposal()`, `signProposal()`, `executeProposal()`.
**MCP tools:** `treasury_propose`, `treasury_sign_proposal`, `treasury_list_proposals`.
**Dashboard:** Treasury detail page "Proposals" tab with proposal cards showing status, signatures, sign/reject/execute buttons.
**DB migrations:** 100 (treasury_signing_mode), 101 (treasury_signing_mode column), 102 (treasury_delegations), 103 (treasury_proposals + proposal_signatures), 104 (auto_approve_rules).

### Agent Chat & Channels (v0.43)
**Agent Chat** — Send messages to agents via Shroud LLM proxy with persistent conversation history. SSE streaming support. **Agent-to-agent chat:** `POST /v1/agents/{id}/chat` supports agent callers for inter-agent communication (same-org only), enabling the sub-agent framework's `delegate_task` tool. Endpoints: `POST /v1/agents/{id}/chat` (send, SSE), `POST .../chat/unlock` (step-up auth), `GET .../chat/conversations` (list), `GET/DELETE .../chat/conversations/{id}`. Runtime chat: `POST /v1/runtimes/{id}/chat` (SSE via in-container bridge). SDK: `client.chat.*` (sendMessage, sendMessageStream, listConversations, getConversation, deleteConversation). MCP: `send_chat_message`, `list_chat_conversations`.

**Messaging Channels** — Connect agents to Telegram, WhatsApp, and Discord for bi-directional messaging with auto-respond via Shroud LLM. Per-channel sender allowlists (`sender_allowlist TEXT[]`), Telegram dedup (`last_telegram_update_id`), WhatsApp HMAC verification (`X-Hub-Signature-256`), and `auto_respond_enabled` toggle. Image generation delivery (DALL-E images delivered inline via Telegram `sendPhoto`). Endpoints: `POST/GET /v1/agents/{id}/channels` (CRUD), `POST .../channels/{id}/send`, `.../test`, `.../refresh-webhook`, `GET .../messages`. Webhook endpoints: `POST /v1/webhooks/telegram/{path}`, `GET/POST /v1/webhooks/whatsapp/{path}`, `POST /v1/webhooks/discord/{path}`. MCP: `create_channel`, `list_channels`, `send_channel_message`. DB: `agent_channels`, `channel_messages` (migrations 152-153, 155, 168-169).

### Hermes-Native Channel Features (v0.45)

- **Slash command router** — 12 built-in commands: /help, /new, /model, /personality, /retry, /undo, /compress, /stop, /status, /skills, /usage, /sethome. Enabled per-channel via `slash_commands_enabled`.
- **Voice memo transcription** — Telegram voice messages auto-transcribed via Whisper API. Enable per-channel with `voice_transcription_enabled`.
- **Cross-platform conversation continuity** — `unified_conversation_id` links channels to a shared conversation context, enabling seamless cross-platform agent interactions.
- **Automation → channel delivery** — `notify` step supports `channel` type for delivering automation outputs to messaging channels.
- **Context-aware interruption** — `auto_respond_in_progress` flag prevents duplicate responses during concurrent message processing.
- **Platform presence** — `is_home_platform` marks a channel as the agent's primary interface. Set via /sethome slash command.
- **Sub-agent chat** — Agents can chat with any agent in the same organization via `POST /v1/agents/{id}/chat` (not just self).
- **Shroud image gen fallback** — DALL-E requests use OPENAI_API_KEY env var when no agent-specific key is configured.

### Agent Memory (v0.42)
Three-tier memory system for AI agents. **Scratch memory** is ephemeral (TTL-based, auto-expired by background reaper). **Durable memory** persists across sessions for long-term state. **Semantic memory** enables vector search via pgvector for retrieval-augmented workflows. All tiers encrypted at rest with envelope encryption (same HSM-backed KEK as secrets). Namespace-scoped per agent (max 100 namespaces, 10K entries, 64KB per value). Endpoints: `GET /v1/agents/{id}/memory` (list namespaces), `GET .../memory/{namespace}` (list entries), `PUT .../memory/{namespace}/{key}` (upsert), `GET .../memory/{namespace}/{key}` (get), `DELETE .../memory/{namespace}/{key}` (delete), `POST .../memory/search` (semantic search). SDK: `client.memory.put()`, `.get()`, `.list()`, `.delete()`, `.search()`. CLI: `1claw memory put|get|list|delete|search`. MCP: `memory_put`, `memory_get`, `memory_list`, `memory_search`, `delete_memory`. Dashboard: Memory card on agent detail page with tier tabs and search UI. DB: migrations 145 (`agent_memory_entries`), 146 (`agent_memory_vectors` with pgvector).

### Automations (v2)
- **14-step workflow engine** — Cron, webhook, event, and manual automation pipelines with AI integration, conditional logic, and variable passing. 14 step types: `log`, `http`, `wait`, `swap`, `submit_transaction`, `execute_intent`, `rotate_generate`, `ai_generate`, `memory_get`, `memory_put`, `memory_search`, `notify`, `approval_request`, `condition`. Create requires `workflow_spec` (+ `agent_id`; `cron_expr` for cron). Template variables: `{{steps.<n>.output}}`, `{{webhook_payload.<path>}}`. Conditional execution: `skip_if`/`run_if` expressions on steps. Condition branching: `if_true`/`if_false` sub-step arrays. 10 marketing presets via `GET /v1/automations/presets` (public). Enriched list API with `last_run_status`, `total_runs`, `success_rate`, `agent_name`. Cancel run: `POST /v1/automations/{id}/runs/{run_id}/cancel` (human-only). Webhook triggers with `whk_` tokens. NL assist: `POST /v1/automations/assist/draft`. Tier-gated: Free 2 (100 runs/mo), Pro 10 (5K), Team 50 (50K), Business 200 (500K). Endpoints: `POST/GET /v1/automations`, `GET/PATCH/DELETE /v1/automations/{id}`, `POST .../trigger`, `POST .../runs/{id}/cancel`, `GET .../runs`, presets, webhook, assist. SDK: `client.automations.*`. CLI: `1claw automation`. MCP: `list_automations`, `trigger_automation`. Dashboard: `/automations` with preset gallery, enriched stats, cancel, `/automations/assist` NL assistant.

### Cloud Runtimes (v0.42; interactive shell v0.43+)
Deploy AI agents in managed containers with preset resource classes. Presets: `small` (0.5 vCPU / 512MB), `medium` (1 vCPU / 1GB), `large` (2 vCPU / 4GB), `large-cc` (4 vCPU / 8GB confidential compute with AMD SEV-SNP). Features: public URL hosting, idle auto-stop, log streaming, health monitoring, environment variable injection from vault secrets, optional **interactive shell** (human-only step-up auth), and a **pluggable tool registry** (per-template `tools-config.js`). Shell: `POST /v1/runtimes/{id}/shell/session` (+ `/shell/passkey/begin`); returns `session_token` + `ws_url` for binary PTY WebSocket. Vault may auto-repair Cloud Run invoker IAM and reconcile shroud sidecar on connect. Tier-gated. Endpoints: `POST /v1/runtimes` (create), `GET /v1/runtimes` (list), `GET /v1/runtimes/{id}` (get), `PATCH /v1/runtimes/{id}` (update), `DELETE /v1/runtimes/{id}` (delete), `POST /v1/runtimes/{id}/start` (start), `POST /v1/runtimes/{id}/stop` (stop), `GET /v1/runtimes/{id}/logs` (stream logs), shell session routes above. SDK: `client.runtimes.create()`, `.list()`, `.get()`, `.update()`, `.delete()`, `.start()`, `.stop()`, `.logs()`, `.createShellSession()`, `.beginShellPasskey()`. CLI: `1claw runtime create|list|get|update|delete|start|stop|logs`. MCP: `list_runtimes`, `manage_runtime`, `runtime_status`, `runtime_logs`. Dashboard: `/runtimes` listing, `/runtimes/new` deploy wizard, `/runtimes/[id]` detail with log viewer, Terminal tab. DB: migrations 144 (`runtimes`), 147 (`runtime_hosting`).

### Runtime Tool Registry (v0.45)
Pluggable tool modules at `packages/runtime-base/templates/shared/tools/` available to agents in Cloud Runtimes. 13 modules: `tool-registry.js` (orchestrator), `image-gen.js` (DALL-E via Shroud — bypasses Stripe AI Gateway), `web-search.js` (Brave/Tavily/SerpAPI), `memory-tools.js` (agent memory CRUD), `file-handler.js` (image analysis + URL reader), `code-exec.js` (sandboxed execution), `google-tools.js`, `github-tools.js`, `slack-tools.js`, `social-tools.js`, `vault-tools.js` (direct vault access), `notify-tools.js` (multi-channel notifications), `sub-agents.js` (inter-agent delegation). Each module exports `definitions` (OpenAI function-calling schema), `execute(name, args, context)`, and `isAvailable(env)`. Per-template configs in `tools-config.js` (hermes, openclaw, openclaude). Dashboard: `RuntimeToolsCard` component shows enabled tools per runtime.

### Sub-Agent Framework (v0.45; delegation v0.46)
Inter-agent communication, task delegation, and human-controlled authorization. **Agent-to-agent delegation** requires an explicit `agent_delegations` record created by a human — agents cannot create/modify/revoke their own delegations (403).

**Delegation model:** `agent_delegations` table (migration 176): `delegator_id`, `delegate_id`, `allowed_tools` (TEXT[]), `blocked_tools` (TEXT[]), `max_daily_delegations` (INTEGER), `max_depth` (1–10), `guardrails` (JSONB), `delegation_mode` (`caller`|`target`|`both`), `is_active`, `created_by`, `expires_at`. `delegation_events` table (migration 177) tracks invocations for rate limiting. `agents.delegation_enabled` BOOLEAN.

**Delegation modes:** `caller` (delegate uses own credentials, default), `target` (delegate uses target agent's config/tools), `both` (caller chooses per invocation).

**Security:** Self-delegation blocked (400). Tool allowlist/blocklist enforced. Daily rate limit via `delegation_events` count. Depth limit prevents recursive chains (`X-Delegation-Depth` header). Expired delegations rejected. Audit events: `agent.delegation.created/updated/revoked/invoked/blocked`.

**Chat enforcement:** `POST /v1/agents/{id}/chat` for agent callers: self-chat always allowed; cross-agent requires active delegation (same org). Delegation engine validates expiry, tools, daily limit, depth.

**Endpoints:** `POST/GET /v1/agents/{id}/delegations` (create: human-only; list: human sees all, agent sees own), `GET .../delegations/effective` (agent-callable for runtime tool discovery), `GET/PATCH/DELETE .../delegations/{delegation_id}` (get/update/revoke: human-only).

**Runtime tools** (`sub-agents.js`): `discover_agents` (search directory), `delegate_task` (send task with `execution_mode` param, `X-Delegation-Depth` tracking, delegation-aware 403 errors), `list_my_sub_agents` (merged with delegation status: `{ authorized, mode, allowed_tools, remaining_daily }`), `create_sub_task` (trigger automation), `get_delegation_status` (check authorized delegates with tool/limit details).

**SDK:** `client.agents.createDelegation()`, `.listDelegations()`, `.getDelegation()`, `.updateDelegation()`, `.revokeDelegation()`, `.getEffectiveDelegations()`. **MCP:** `list_delegations`, `create_delegation`, `get_effective_delegations`. **CLI:** `1claw agent delegation create|list|get|update|revoke`.

**Dashboard:** Sub-agent creation wizard (`/agents/sub-agent-wizard`) — 4-step flow with 6 role presets (Research, Image Gen, Treasury, Comms, Code, Custom), multi-parent delegation rules. Delegations tab on agent detail (outbound/inbound tables with CRUD dialogs). Sub-Agents card with authorization badges. Agents list with sub-agent indicators.

**Tests:** `test-sub-agents-prod.sh` (~55 assertions), `test-delegation-security-prod.sh` (~25 security assertions).

### Agent Discovery (v0.42)
Public agent directory and platform marketplace. Agents can be made discoverable with capability cards showing A2A protocol URLs, MCP server endpoints, supported protocols, pricing, and categories. Public search and browse. Endpoints: `GET /v1/agents/directory` (search/browse, public, no auth), `GET /v1/agents/{id}/card` (get agent's public card, no auth), `PATCH /v1/agents/{id}/discovery` (update discovery settings, human-only), `GET /v1/platform/marketplace` (browse platform app marketplace, public). SDK: `client.discovery.getAgentCard()`, `.directory()`, `.updateDiscovery()`, `.marketplace()`. CLI: `1claw directory search|card`. MCP: `search_agent_directory`. Dashboard: `/directory` public listing page, discovery card on agent detail. DB: migration 148 (`agent_discovery`), 149 (`platform_listing`).

### Platform API (v0.20)
**Platform delegation (v0.42; scope enforcement v0.44)** — Platform apps can perform CRUD operations on connected user resources by passing the `X-Platform-Connection` header with the connection ID. Scoped by `delegation_enabled` (boolean) and `delegation_scopes` (TEXT[] — e.g. `["vaults:read", "secrets:read", "secrets:write", "agents:read"]`) on platform connections. Delegation scopes enforced on 4 handler groups: secrets, policies, bindings, and discovery. Disconnected connections rejected with 403. All delegated operations attributed to the platform app in audit logs. DB: migrations 151, 170.

**OAuth2 credential bindings (v0.42)** — Execution Intents bindings now support OAuth2 credential type with two grant flows: `authorization_code` (interactive, with PKCE) and `client_credentials` (server-to-server). Configuration stores client ID, client secret (encrypted), token URL, authorization URL, and scopes. Tokens are automatically refreshed before execution when expired. DB: migration 150 (`oauth2_credential_bindings`).

**OAuth Connected Accounts (v0.44)** — Universal OAuth integration for AI agents. Connect agents to external services (Google, GitHub, X/Twitter, LinkedIn, Slack, Discord, Notion, Microsoft, Salesforce, HubSpot) via human-approved OAuth flows. Provider registry seeded with 10 providers (each defines slug, authorization_url, token_url, scopes_available, default_scopes, extra_auth_params). Flow: human saves org-level app credentials → initiates connection for agent → user completes OAuth consent → callback stores tokens as execution binding → agent accesses external service via execution intents (auto-refresh). Endpoints: `GET /v1/oauth/providers` (public), `POST /v1/agents/{id}/oauth/connect` (human-only, returns authorization_url), `GET /v1/agents/{id}/oauth/connections`, `POST /v1/agents/{id}/oauth/disconnect/{bindingId}`, `POST/GET/DELETE /v1/agents/{id}/oauth/app-credentials`, `GET /v1/oauth/callback` (public callback). SDK: `OAuthConnectResource` — `listProviders()`, `listConnections()`, `connect()`, `disconnect()`, `saveAppCredentials()`, `listAppCredentials()`, `deleteAppCredentials()`. MCP: `list_oauth_providers`, `list_oauth_connections`. CLI: `1claw oauth providers|connections|connect|disconnect|credentials`. Dashboard: `ConnectedAccountsCard` on agent detail page. DB: `oauth_provider_registry` (migration 171, seeded), `oauth_app_credentials` (migration 172, envelope-encrypted).

For developers building applications on top of 1Claw. Platform apps (`plt_` API keys, `principal_type: "platform"`) provision users, vaults, agents, and policies on behalf of end-users via declarative bootstrap templates. OIDC user provisioning via `POST /v1/platform/users/upsert` (accepts `subject_token` JWT verified against platform JWKS, or email). Bootstrap: `POST /v1/platform/connections/{id}/bootstrap` creates resources from a template spec and returns a claim URL; accepts optional `parameters` (template variables), `Idempotency-Key` (24h replay protection), and `return_to`. **Platform API expansion (v0.57):** SIWE wallet login via `POST /v1/platform/siwe/challenge` + upsert with `subject_token_type: urn:1claw:params:oauth:token-type:siwe`, `siwe_message`, `siwe_signature`. **SIWE signatures:** 65-byte ECDSA hex; final byte is recovery id. MetaMask/viem/ethers emit **v=27/28** (EIP-191); legacy **0/1** also accepted. Invalid recovery ids → 400 (`expected recovery id 0, 1, 27, or 28, got {v}`). `GET /v1/platform/connections/{id}` (connection detail), `GET .../usage`, `GET .../entitlements`, `POST .../entitlements/refresh` (on-chain entitlement sync), `POST /v1/platform/apps/{id}/templates/{tid}/preview` (dry-run template with parameters). **App-scoped reads (`plt_`):** `GET .../connections/{id}/approvals`, `GET .../approvals/{approval_id}`, `GET .../pending-approvals` (includes `action_payload` + `payload_hash` SHA-256 hex of canonical JSON), `GET .../spend-policy` (effective policy). **Human JWT:** `PUT .../connections/{id}/spend-policy` (optional `Idempotency-Key` — 24h replay, body-hash mismatch → 409), `POST /v1/approvals/{id}/decide`. **App lifecycle:** `PATCH` rejects `slug` changes (400); `DELETE` soft-deactivates app, returns `{ id, slug, deleted_at }`, releases slug; `GET /v1/platform/apps/{id}` → **404** when inactive. Slugs unique per org (migration 216). `POST /v1/platform/apps/{id}/transfer-ownership` moves app to another org (step-up `platform.app.transfer`). Spend policies support inference allowances; Shroud enforces per-request caps. Webhooks: `platform.user.claimed`, `platform.claim.expired`, `platform.entitlement.granted`, `platform.entitlement.revoked`. **Claim flow**: `GET /v1/platform/claim/{token}` previews provisioned resources (public, no auth); `POST /v1/platform/claim/{token}` redeems the one-time claim (409 if reused, 410 if expired). Dashboard claim page at `/connect/{slug}/claim/{token}`. Bootstrap templates support `signing_keys` arrays on agent entries (auto-provision per-chain signing keys), plus `runtimes` and `automations` arrays to bootstrap managed containers and workflows. Bootstrap response includes `summary.agent_api_key` (one-time `ocv_` key), `summary.signing_keys[]` (each with `chain`, `curve`, `public_key`, `address`), and resource IDs tracked on the connection (`runtime_ids`, `automation_ids`). Three billing models: `platform_pays` (default), `user_pays`, `hybrid`. Three auth modes: `silent`, `user_signin`, `configurable`. `platform_locked` flag on vaults/agents prevents operator access to secret values. Optional `siwe_domain` on platform apps for Sign-In with Ethereum. DB tables: `platform_apps`, `platform_templates`, `platform_user_connections`, `platform_user_grants`, `platform_claim_tokens` (migration 215 adds bootstrap idempotency, inference spend, entitlement watches; migration 217 spend-policy PUT idempotency). New columns on `vaults` (platform_app_id, platform_locked, billed_to_type, billed_to_id), `agents` (platform_app_id, platform_locked). Dashboard at `/platform` with visual **Template Spec Builder** UI for building bootstrap templates without raw JSON editing. SDK: `client.platform.*` (incl. `siweChallenge`, `getConnection`, `getConnectionUsage`, `listConnectionApprovals`, `getConnectionApproval`, `listConnectionPendingApprovals`, `getConnectionSpendPolicy`, `getSpendPolicy`, `transferAppOwnership`, `deleteApp` → `PlatformAppDeleteResponse`). CLI: `1claw platform siwe-challenge`, `connection`, `template-preview`. MCP registry `io.github.1clawAI/1claw-mcp` @ **0.59.0**. List endpoints return wrapped JSON objects: `GET /v1/platform/apps` → `{ apps: [...] }`, `GET .../templates` → `{ templates: [...] }`, `GET .../users` → `{ users: [...] }`.

**Platform API (v0.59.4):** Connection-scoped **`GET .../portfolio`** (alias `.../balances`), **`POST .../pending-approvals`** (create consensus approval), **`GET/POST .../automations`**, **`GET/PUT/DELETE .../memory/{namespace}/{key}`**, **`POST /v1/shroud/inspect-content`**. v0.59.3: signing-keys, agent PATCH, connection chat/passkey/runtime. **`platform_pays` + template `plan` → `provisioned_tier`**; **`siwe_domain`** on apps (plt_ PATCH-only); **`Idempotency-Key`** on bootstrap + spend-policy PUT. Platform webhooks: `pending_approval.created`, `tx.awaiting_approval`, `sign.awaiting_approval`, `automation.run.failed`. Packages @ **0.59.4**.

**Platform idempotency matrix:** `POST .../bootstrap` — `Idempotency-Key` + SHA-256(body), 24h replay, mismatch → 409. `PUT .../connections/{id}/spend-policy` — same pattern (migration 217). Transaction submit and internal transfers also support `Idempotency-Key` elsewhere in the API.

### Execution Intents (v0.39 / 2.0)
Agents can make HTTP calls, GraphQL queries, and other external service interactions through pre-configured **bindings**. Credentials are stored server-side and never exposed to agents. Trait-based executor framework with shared `ExecutionContext` (SSRF, host/path allowlists, credential injection, timeouts). Real GraphQL executor (query/variables/operationName, surfaces `errors[]`). Binding types: HTTP, GraphQL (Pro tier), Postgres, MySQL, Redis, gRPC, SMTP, Cloud SDK, S3, Custom (Team+ tier). TEE execution mode on Business+ (`execution_surface`: `vault`/`tee`). Per-binding `allowed_hosts`/`allowed_paths`; agent `execution_guardrails` (`allowed_hosts`, `allowed_binding_types`, `max_duration_ms`, `max_requests_per_minute`). Credential rotation: `POST .../rotate-credential`; `credential_set` on responses; delete purges credential. **Live-pointer credential references (v0.41):** `credential_source` field with `Inline` (default — credential copied at creation) and `VaultRef` (`{ type: "vault_ref", vault_id, path }` — credential resolved at execution time from the referenced vault secret; changes are automatically reflected without manual rotation). Only successful executions count toward monthly quota. Endpoints: CRUD under `/v1/agents/{id}/bindings`, `POST .../execute`, `POST .../bindings/{id}/test`. Agent field `execution_intents_enabled`. SDK: `client.bindings.*` (incl. `rotateCredential`). CLI: `1claw agent binding *`. MCP: `execute_http`, `execute_intent`, `list_bindings`, `create_binding`, `test_binding`, `list_executions`. Dashboard: Execution Intents card on agent detail (binding create/edit includes "From Vault" option for vault_ref credential source).

### Mobile Companion App (v0.21, beta)
Human-in-the-loop approval app for iOS + Android, built with Expo SDK 54, expo-router, TanStack Query, and Zustand. Features: passkey + biometric + PIN authentication, approval inbox with risk tiers (Tier 1 info-only, Tier 2 biometric, Tier 3 TOTP) and countdown timers, agent management with quarantine, policy editor, treasury wallets, audit log, Shroud activity feed, and **Expo push notifications** on pending approvals when `ONECLAW_EXPO_ACCESS_TOKEN` is configured (best-effort via `domain/push_notify.rs`). Backend API: `POST/GET /v1/auth/devices` (register/list mobile devices; store Expo push token via `POST .../push-token`), `POST /v1/auth/devices/{id}/challenge` + `attest` (step-up auth), `GET /v1/approvals` + `POST /v1/approvals/{id}/decide` (approval queue). SDK: `client.devices.*`, `client.passkeys.*`, `client.approvals.*`. TestFlight deployment via EAS Build. DB: migrations 092–096 (user_devices, device_challenges, step_up_tokens, user_passkeys, approvals).

### Sharing
Secrets can be shared between users and agents via links (with optional passphrase and IP restrictions), direct user/agent shares, email invites (humans only), or "share back to creator" for agents. Inbound shares require explicit accept/decline.

### Shroud (TEE Proxy)
Rust service running inside Google Cloud Confidential GKE (AMD SEV-SNP). Sits between AI agents and LLM providers, performing real-time security inspection of all traffic. Supports OpenAI, Anthropic, Google Gemini, Mistral, Cohere, OpenRouter, Darkbloom (E2E encrypted Apple Silicon TEE), Venice AI (zero-retention + optional TEE/E2EE), and Bankr LLM Gateway. Also handles transaction signing with keys that never leave the TEE. **Intents on Shroud:** before signing, Shroud fetches agent guardrails from the Vault API (including daily spend vs limit). User-defined **`output_policy.blocked_patterns`** regexes are size-limited server-side (pattern count and length caps) to reduce ReDoS risk.

**LLM routing:** Authenticated `POST /v1/chat/completions` (and related LLM routes) require the `X-Shroud-Provider` header (e.g. `openai`, `anthropic`, `google`); omitting it returns **400**. When the org has LLM token billing enabled, eligible traffic can be routed through Stripe AI Gateway (see Vault billing endpoints below).

**Per-org secret redaction:** Shroud maintains per-org Aho-Corasick automata for secret redaction. A background task calls `GET /v1/admin/secrets/manifest` (platform admin key) to fetch all secrets across all orgs, partitioned by `org_id`. Each request's `org_id` (from the agent JWT) selects the correct automaton — org A's secrets never leak into org B's `[REDACTED:#hashprefix]` labels. `__agent-keys` vaults and MPC vaults are excluded from the manifest.

**Request inspection pipeline** (in order): hidden content stripping → per-org secret redaction (Aho-Corasick) → secret injection detection (catches non-vault credentials in prompts) → PII detection → context injection defense → prompt injection scoring → token counting → Unicode normalization → command injection detection → encoding detection → social engineering detection → network detection → filesystem detection → tool call inspection → semantic policy → policy enforcement.

**Response inspection pipeline** (Shroud v0.5.0+, in order): token counting → tool call inspection → output policy (blocked patterns, harmful content categories) → **response injection** (echoed/indirect injection, markdown-image exfil, data-URI blobs, unexpected code fences) → **prompt injection (response-side)** → **context injection (response-side)** → **network detection (response-side)** (exfil URLs in model output) → response filtering (hallucinated credentials) → secret redaction → semantic policy. Bi-directional inspection adds audit fields `response_injection_score`, `response_context_injection_score`, `response_injection_categories`, `external_urls_flagged`, `unexpected_code_blocks`. Server-side toggles: `enable_response_injection_detection`, `enable_response_network_detection`, `enable_response_code_block_detection` (all default true).

Per-agent configuration: each agent has `shroud_enabled` (boolean) and `shroud_config` (JSON) fields. Config options: `pii_policy` (block/redact/warn/allow), `injection_threshold` (0.0–1.0), `context_injection_threshold`, `allowed_providers`, `allowed_models`, `denied_models`, `max_tokens_per_request`, `max_requests_per_minute`, `max_requests_per_day`, `daily_budget_usd`, `enable_secret_redaction`, `enable_response_filtering`, plus threat detectors (social engineering, network, encoding, command injection, filesystem, tool call inspection, output policy, secret injection detection, advanced redaction, semantic policy) with actions **block** / **warn** / **log** where applicable. Additional config: `tool_call_inspection` (allowed_tool_names, denied_tool_names, scan_arguments, block_credential_exfil), `output_policy` (blocked_patterns, blocked_entities, block_harmful_content, harmful_categories: violence/self_harm/illegal/hate/sexual/malware), `secret_injection_detection` (sensitivity: low/medium/high), `advanced_redaction` (detect_base64_encoded, detect_split_secrets, detect_prefix_leak, min_secret_length), `semantic_policy` (allowed_topics, denied_topics, allowed_tasks, denied_tasks), `flagged_request_retention_days`. All options are fully configurable via the dashboard (Agent → Shroud LLM Proxy card with collapsible sections: Basic Settings, Rate Limits & Budget, Threat Detection with per-detector sub-options, Extended Inspection), API (`PATCH /v1/agents/{id}`), SDK, or CLI (`1claw agent update <id> --shroud true`).

**Enforcement:** Vault embeds `shroud_config` on the **agent JWT** when `shroud_enabled` is true (`POST /v1/auth/agent-token`). Shroud runs the request inspection pipeline, then **PolicyEngine** uses the JWT payload so per-agent **block** settings take effect. The response pipeline runs after the LLM responds. Re-exchange agent credentials after changing Shroud config.

## API (OpenAPI 3.1)

Base URL: `https://api.1claw.co`

Key endpoints:
- `POST /v1/auth/token` — Login
- `POST /v1/auth/forgot-password` — Request reset email (returns `status`: `email_sent`, `no_account`, or `social_account`; rate-limited to prevent enumeration)
- `POST /v1/auth/reset-password` — Complete reset with token from email
- `DELETE /v1/auth/token` — Revoke current Bearer token (returns 200; reused token then returns 401)
- `POST /v1/auth/agent-token` — Agent token exchange (accepts `api_key` alone or `agent_id` + `api_key`; returns `agent_id` and `vault_ids` for auto-discovery)
- `POST /v1/auth/federated-token` — RFC 8693 OIDC token exchange. Subject token (agent JWT or `ocv_` key) → short-lived RS256 JWT. Requires `agent.federation_enabled=true` and audience on `agent.federation_audiences`. Default TTL 15 min, hard cap 60 min.
- `GET /.well-known/openid-configuration` — Public OIDC discovery (issuer, jwks_uri, supported algs `["EdDSA","RS256"]`, supported grant types incl. token-exchange)
- `GET /.well-known/jwks.json` — Public JWKS (every active EdDSA + RS256 key version, keyed by `kid`, 5-min cache, CORS `*`)
- `GET/PATCH/DELETE /v1/auth/me` — Get/update/delete own account (user-only; delete requires `{ confirmation: "DELETE MY ACCOUNT" }`)
- `POST /v1/auth/set-password` — Set first password for platform-provisioned OIDC/Google users (user-only, rejects if password already set)
- `POST /v1/auth/change-email` — Initiate email change (user-only, sends verification code to new address)
- `POST /v1/auth/verify-email-change` — Complete email change with verification code
- `POST /v1/auth/passkeys/register/begin` — Start WebAuthn passkey registration (authenticated)
- `POST /v1/auth/passkeys/register/complete` — Complete passkey registration with attestation
- `POST /v1/auth/passkeys/assert/begin` — Start passkey login (public, accepts `{ email }`)
- `POST /v1/auth/passkeys/assert/complete` — Complete passkey login (public, returns JWT)
- `GET /v1/auth/passkeys` — List registered passkeys (authenticated)
- `DELETE /v1/auth/passkeys/{id}` — Delete a passkey (authenticated)
- `POST /v1/auth/export-data` — GDPR data export: returns JSON archive of user's profile, vaults, agents, secret metadata, and policies (user-only)
- `POST/GET /v1/auth/devices` — Register/list mobile devices (user-only)
- `DELETE /v1/auth/devices/{id}` — Revoke a mobile device
- `POST /v1/auth/devices/{id}/challenge` — Create step-up auth challenge
- `POST /v1/auth/devices/{id}/attest` — Attest device challenge with device key signature
- `POST /v1/auth/devices/{id}/push-token` — Register push notification token
- `GET /v1/approvals` — List pending approval requests (user-only)
- `GET /v1/approvals/{id}` — Get approval details
- `POST /v1/approvals/{id}/decide` — Approve or reject (auto-executes `policy_change` and `card_order` on approval; risk tier 2+ requires `X-Auth-Confirm` re-auth)
- `GET /v1/approvals/quick-decide` — Public one-click approve/deny from email (`token` + `decision` query params; redirects to dashboard)
- `POST /v1/approvals/request` — Agent-initiated approval request (agent-only, directed to agent's creator)
- `GET/POST /v1/vaults` — List/create vaults
- `GET/DELETE /v1/vaults/{id}` — Get/delete vault
- `POST/DELETE /v1/vaults/{id}/cmek` — Enable/disable CMEK
- `POST /v1/vaults/{id}/cmek-rotate` — Start CMEK rotation
- `GET/PUT/DELETE /v1/vaults/{id}/secrets/{path}` — CRUD secrets
- `GET/POST /v1/agents` — List/create agents
- `POST /v1/agents/enroll` — Agent self-enrollment (public, no auth, emails credentials to human)
- `GET /v1/agents/me` — Agent self-profile (includes created_by)
- `GET/PATCH/DELETE /v1/agents/{id}` — Get/update/delete agent
- `POST /v1/agents/{id}/rotate-identity-keys` — Rotate agent SSH/ECDH keys (user-only)
- `GET /v1/vaults/{id}/secret-versions/{path}` — List secret versions
- `GET /v1/vaults/{id}/secret-version/{path}/{version}` — Get specific version
- `POST /v1/vaults/{id}/secret-version-disable/{path}/{version}` — Disable a secret version
- `POST /v1/vaults/{id}/secret-rotate/{path}` — Server-side secret rotation
- `POST /v1/agents/{id}/transactions` — Submit transaction (over signature quota: flat per-signature overage, 402 if unpaid)
- `POST /v1/agents/{id}/transactions/sign` — Sign transaction without broadcasting (returns signed_tx + tx_hash)
- `POST /v1/agents/{id}/sign` — Unified signing intent (personal_sign, typed_data, eip712_digest, or transaction with tx_type 0–4)
- `POST/GET /v1/agents/{id}/signing-keys` — Create/list multi-chain signing keys
- `POST /v1/agents/{id}/signing-keys/{chain}/rotate` — Rotate signing key for a chain
- `DELETE /v1/agents/{id}/signing-keys/{chain}` — Deactivate signing key
- `POST /v1/agents/{id}/signing-keys/{chain}/export` — Export signing key with private key (requires `X-Auth-Confirm` password header, human-only, audit-logged)
- `POST /v1/agents/{id}/transactions/simulate` — Simulate transaction
- `GET/POST /v1/shroud/activity` — Shroud inspection events and flagged requests
- `GET /v1/shroud/threat-summary` — Shroud threat detection summary
- `GET /v1/risk/events` — List risk events (filterable by severity, principal_type)
- `GET /v1/risk/verdicts` — List active risk verdicts
- `GET /v1/risk/verdicts/{type}/{id}` — Get verdict for a specific principal
- `GET/POST/DELETE /v1/risk/honeytokens` — CRUD honeytoken canary secrets
- `GET/POST /v1/vaults/{id}/policies` — List/create policies
- `POST /v1/secrets/{id}/share` — Share a secret (agents use recipient_type: "creator" to share with their human)
- `GET /v1/audit/events` — Query audit log
- `GET /v1/billing/subscription` — Billing status
- `GET /v1/billing/llm-token-billing` — LLM add-on status (`enabled`, `subscription_status`); when Stripe returns data, may include `credit_balance` and `billing_cycle_usage` with optional `metered_lines[]` (per-line accrued usage from the upcoming invoice)
- `GET /v1/chains` — Supported blockchains
- `GET/POST /v1/treasury` — List/create treasuries
- `GET /v1/treasury/{id}` — Get treasury (signers, access-request sub-routes)
- `POST /v1/treasury/wallets/generate` — Generate multi-chain treasury wallets (human-only; wallet quota)
- `GET /v1/treasury/wallets` — List user's treasury wallets
- `GET /v1/treasury/wallets/{chain}` — Get wallet by chain
- `POST /v1/treasury/wallets/{chain}/export` — Export wallet with private key (requires `X-Auth-Confirm` password header)
- `POST /v1/treasury/wallets/{chain}/rotate` — Rotate wallet keypair
- `DELETE /v1/treasury/wallets/{chain}` — Deactivate wallet
- `GET /v1/treasury/wallets/{chain}/balance` — Query native + ERC-20 token balances via chain RPC (human-only)
- `POST /v1/treasury/wallets/{chain}/send` — Signed transfer from treasury wallet (human-only, requires `X-Auth-Confirm` re-auth). Supports `gasless: true` for ERC-4337 UserOperation with Pimlico paymaster sponsorship (response includes `user_op_hash`)
- `POST /v1/treasury/wallets/{chain}/swap` — DEX aggregator token swap via 0x API (human-only, requires `X-Auth-Confirm` re-auth)
- `GET /v1/agents/{id}/signing-keys/{chain}/balance` — Query native + ERC-20 balances for an agent's signing key address
- `POST /v1/agents/{id}/cards/order` — Order a prepaid/gift card via x402 (agent, requires `cards_enabled` + `Idempotency-Key`; never returns a PAN)
- `GET /v1/cards` — List payment cards (masked to last4)
- `GET /v1/cards/{id}` — Get a payment card (masked)
- `POST /v1/cards/{id}/reveal` — Reveal full card details (human: `X-Auth-Confirm` password; agent: only if per-card reveal policy allows; audit-logged)
- `PATCH /v1/cards/{id}` — Update reveal policy / `void_after` (human-only)
- `POST /v1/cards/{id}/void` — Void a card (1Claw-level lock; forward-looking only)
- `POST /v1/cards/{id}/refresh` — Refresh balance/status from Laso (rate-limited; 429 + Retry-After)
- `POST /v1/cards/import` — Manually import a card (human-only, full encrypted storage)
- `POST /v1/cards/gift-cards/search` — Search available Laso gift-card brands/servers
- `POST/GET /v1/webhooks` — Create/list webhook registrations (wallet, proposal, transaction events)
- `GET/PATCH/DELETE /v1/webhooks/{id}` — Get/update/delete a webhook registration
- `POST /v1/treasury/{id}/proposals` — Create treasury proposal (agent or user)
- `GET /v1/treasury/{id}/proposals` — List proposals (filterable by ?status=)
- `GET /v1/treasury/{id}/proposals/{pid}` — Get proposal with signatures
- `POST /v1/treasury/{id}/proposals/{pid}/sign` — Sign proposal (approve/reject; auto-executes at threshold)
- `POST /v1/treasury/{id}/proposals/{pid}/execute` — Force-execute proposal (user-only)
- `DELETE /v1/treasury/{id}/proposals/{pid}` — Cancel pending proposal
- `POST /v1/platform/apps` — Register platform app (user-only, returns plt_ key)
- `GET /v1/platform/apps` — List platform apps
- `GET/PATCH/DELETE /v1/platform/apps/{id}` — Get/update/soft-delete platform app (DELETE → 200 + slug released; GET → 404 when inactive)
- `POST /v1/platform/apps/{id}/transfer-ownership` — Transfer app to another org (human JWT + step-up)
- `POST/GET /v1/platform/apps/{id}/templates` — Create/list bootstrap templates
- `POST /v1/platform/users/upsert` — Provision or find user (platform-only, OIDC or email)
- `POST /v1/platform/connections/{id}/bootstrap` — Bootstrap resources from template (optional `parameters`, `Idempotency-Key`)
- `POST /v1/platform/siwe/challenge` — SIWE challenge for wallet-based user upsert (platform-only)
- `GET /v1/platform/connections/{id}/runtimes/{runtime_id}` — Connection-scoped runtime GET (plt_; not `/v1/runtimes/{id}`)
- `POST /v1/platform/connections/{id}/passkeys/enroll/begin` — ALWAYS 403. Platform apps cannot enrol login passkeys; the user enrols at 1claw.co/settings/security.
- `POST /v1/platform/connections/{id}/passkeys/enroll/complete` — ALWAYS 403. See above.
- `POST /v1/platform/connections/{id}/agents/{agent_id}/chat` — Connection-scoped agent chat (`system`, `system_prompt`, `messages[]`; 402 on billing errors)
- `PATCH /v1/platform/connections/{id}/agents/{agent_id}` — Enable Intents/Execution Intents or update `system_prompt` (plt_; agent on connection)
- `GET /v1/platform/connections/{id}/signing-keys` — List agent signing keys (public metadata; optional `?agent_id=`; not `wallet_address`)
- `GET /v1/platform/connections/{id}/signing-keys/{chain}` — Single-chain agent signing key lookup (plt_)
- `DELETE /v1/platform/connections/{id}/signing-keys/{chain}` — Deactivate connection agent signing key (plt_)
- `GET /v1/platform/connections/{id}` — Connection detail (`provisioned_tier`, `wallet_address` = SIWE staker — not agent key)
- `GET /v1/platform/connections/{id}/approvals` — List approvals for connected user (`plt_`)
- `GET /v1/platform/connections/{id}/approvals/{approval_id}` — Single approval (`plt_`)
- `GET /v1/platform/connections/{id}/pending-approvals` — Consensus pending approvals with `payload_hash` (`plt_`)
- `POST /v1/platform/connections/{id}/pending-approvals` — Create pending approval for connection agent (`plt_`; **202**)
- `GET /v1/platform/connections/{id}/portfolio` — Connection agent portfolio/balances (`plt_`; optional `?chains=`, `?include_tokens=`)
- `GET/POST /v1/platform/connections/{id}/automations` — List/create automations for connection agents (`plt_`)
- `GET/PUT/DELETE /v1/platform/connections/{id}/memory/{namespace}/{key}` — Connection-scoped agent memory (`plt_`)
- `POST /v1/shroud/inspect-content` — Content threat inspection (plt_ / agent / user JWT)
- `GET /v1/platform/connections/{id}/spend-policy` — Effective spend policy for connection (`plt_`)
- `GET /v1/platform/connections/{id}/usage` — Connection usage attribution (platform-only)
- `GET /v1/platform/connections/{id}/entitlements` — List entitlement watches (platform-only)
- `POST /v1/platform/connections/{id}/entitlements/refresh` — Refresh on-chain entitlements (platform-only)
- `POST /v1/platform/templates/preview` — Preview bootstrap template with parameters (platform-only)
- `GET /v1/platform/claim/{token}` — Preview claim token (public, no auth; returns app name, provisioned resources, expiry)
- `POST /v1/platform/claim/{token}` — Redeem claim token (public; marks connection as claimed; 409 if reused, 410 if expired)
- `GET /v1/platform/connected-apps` — List connected apps (user-only)
- `DELETE /v1/platform/connected-apps/{id}` — Disconnect from platform app
- `POST /v1/platform/connections/{id}/grant` — Grant platform app access to selected vaults/agents (user-only)
- `GET /v1/platform/connections/{id}/grants` — List active resource grants for a connection
- `DELETE /v1/platform/connections/{id}/grants/{grant_id}` — Revoke a specific resource grant
- `POST /v1/auth/email-otp/send` — Send 6-digit OTP code to email (public, auth-rate-limited)
- `POST /v1/auth/email-otp/verify` — Verify OTP code, returns JWT + wallet_address (public)
- `GET /v1/oauth/authorize` — Get OAuth consent info (authenticated)
- `POST /v1/oauth/authorize` — Approve/deny OAuth authorization (authenticated, issues code)
- `POST /v1/oauth/token` — Exchange authorization code for access_token + id_token (public)
- `GET /v1/oauth/userinfo` — Get user info (sub, email, name, wallet_address)
- `POST /v1/platform/apps/{id}/spend-policies` — Create app-level spend policy (platform-only)
- `GET /v1/platform/apps/{id}/spend-policies` — List active spend policies
- `GET /v1/platform/apps/{id}/spend-policies/{pid}` — Get spend policy by ID
- `PUT /v1/platform/connections/{id}/spend-policy` — Set per-user spend policy override (human JWT; optional `Idempotency-Key`)
- `GET /v1/treasury/wallets/spend-policy` — View effective spend policy (user-only)
- `GET /v1/treasury/wallets/inference-budget` — Inference spend vs allowance (platform-connected users)
- `DELETE /v1/platform/apps/{id}/spend-policies/{pid}` — Deactivate spend policy
- `GET /v1/agents/{id}/memory` — List memory namespaces
- `GET /v1/agents/{id}/memory/{namespace}` — List entries in a namespace
- `PUT /v1/agents/{id}/memory/{namespace}/{key}` — Upsert a memory entry
- `GET /v1/agents/{id}/memory/{namespace}/{key}` — Get a memory entry
- `DELETE /v1/agents/{id}/memory/{namespace}/{key}` — Delete a memory entry
- `POST /v1/agents/{id}/memory/search` — Semantic vector search over agent memory
- `GET /v1/automations/presets` — List automation presets (public, no auth; 10 marketing-ready templates)
- `POST /v1/automations` — Create an automation (requires `workflow_spec` + `agent_id`; 14 step types)
- `GET /v1/automations` — List automations (enriched: last_run_status, total_runs, success_rate, agent_name)
- `GET /v1/automations/{id}` — Get automation details
- `PATCH /v1/automations/{id}` — Update automation
- `DELETE /v1/automations/{id}` — Delete automation
- `POST /v1/automations/{id}/trigger` — Manually trigger an automation
- `POST /v1/automations/{id}/runs/{run_id}/cancel` — Cancel a running or awaiting_approval run (human-only)
- `GET /v1/automations/{id}/runs` — List automation run history
- `GET /v1/automations/{id}/runs/{run_id}` — Get run details
- `POST /v1/automations/webhook/{id}/{token}` — Public webhook trigger
- `POST /v1/automations/{id}/rotate-webhook-token` — Rotate webhook token (human-only)
- `POST /v1/automations/assist/draft` — NL-to-workflow draft (human-only)
- `POST /v1/automations/assist/session` — Assist session with scoped JWT (human-only)
- `POST /v1/runtimes` — Create a cloud runtime
- `GET /v1/runtimes` — List cloud runtimes
- `GET /v1/runtimes/{id}` — Get runtime details
- `PATCH /v1/runtimes/{id}` — Update runtime configuration
- `DELETE /v1/runtimes/{id}` — Delete runtime
- `POST /v1/runtimes/{id}/start` — Start a runtime
- `POST /v1/runtimes/{id}/stop` — Stop a runtime
- `GET /v1/runtimes/{id}/logs` — Stream runtime logs
- `GET /v1/agents/directory` — Search/browse the public agent directory (no auth)
- `GET /v1/agents/org-directory` — List agents in the caller's organization (authenticated, org-scoped)
- `GET /v1/agents/{id}/card` — Get agent's public card (no auth)
- `PATCH /v1/agents/{id}/discovery` — Update discovery settings (human-only)
- `GET /v1/platform/marketplace` — Browse platform app marketplace (public)
- `GET /v1/oauth/providers` — List available OAuth providers from registry (public, no auth)
- `POST /v1/agents/{id}/oauth/connect` — Initiate OAuth flow for an agent (human-only, returns authorization_url)
- `GET /v1/agents/{id}/oauth/connections` — List agent's OAuth connections
- `POST /v1/agents/{id}/oauth/disconnect/{bindingId}` — Revoke tokens and delete OAuth binding (human-only)
- `POST /v1/agents/{id}/oauth/app-credentials` — Save OAuth app credentials for a provider (human-only)
- `GET /v1/agents/{id}/oauth/app-credentials` — List OAuth app credentials (secrets redacted)
- `DELETE /v1/agents/{id}/oauth/app-credentials/{providerSlug}` — Delete OAuth app credentials
- `GET /v1/oauth/callback` — Public OAuth provider redirect callback

Full spec: https://www.npmjs.com/package/@1claw/openapi-spec

**API limits and security:** Request body size is limited to 5MB (413 if exceeded). Public auth routes (e.g. login, signup) are rate-limited (5 req burst, 1/sec); 429 when exceeded. Revoked tokens (via `DELETE /v1/auth/token`) are rejected with 401. Share creation: 10/min/org. MFA tokens are single-use (jti revoked after verification). TOTP codes are replay-protected — each `(user_id, time_step)` is recorded and rejected on reuse within the ±1 step window. Agent JWTs derive `vault_ids` from access policies when not explicitly set. Agent JWTs are tracked in `agent_active_tokens`; policy changes auto-revoke them (see Policies above). Intents API `signing_key_path` restricted to `keys/*`, `wallets/*`, `agents/{id}/keys/*`, or `agents/{id}/chains/*`. Default auto-resolves per-chain signing keys when provisioned; network names (sepolia, base, etc.) map to canonical chains (ethereum). Audit log inserts use a `SECURITY DEFINER` function — the application role (`vault_app`) cannot insert directly into `audit_events`, preventing log tampering from compromised connections. **Account lockout:** After 10 failed login attempts, accounts are locked for 15 minutes; lockout is automatic and resets on successful login. **Session revocation on password change/reset:** When a user changes or resets their password, all existing sessions (JWTs) are automatically invalidated — the user must re-login. **Agent self-update guard:** Agents cannot `PATCH /v1/agents/{id}` their own record; only human users can update agent configuration (agents receive 403). **MCP exfil protection:** The MCP server defaults to "block" mode for exfiltration protection (prevents secrets from being sent to non-secret tools); configurable via `ONECLAW_MCP_EXFIL_PROTECTION` env var. **x402 payment verification:** All x402 payment paths (authenticated and unauthenticated) verify the actual required payment amount before settling. **System vault read blocking:** Direct API reads from `__agent-keys` and `__treasury-keys` system vaults return 403 — keys are only accessible through their designated export/reveal endpoints. **Treasury wallet export re-auth:** `POST /v1/treasury/wallets/{chain}/export` requires the user's account password in the `X-Auth-Confirm` header. **Unified sign policy enforcement:** `POST /v1/agents/{id}/sign` enforces PolicyEngine access checks and `validate_signing_key_path` before key retrieval; transaction intents enforce all guardrails (chains, allowlist, value caps, daily limits). **Account lockout DoS fix:** Failed login attempt counter auto-resets when the lockout period expires, preventing permanent re-locking from repeated attempts after expiry. **Nonce-based CSP:** Dashboard uses per-request cryptographic nonces with `'strict-dynamic'` in `script-src`, replacing the previous `'unsafe-inline'`-only policy. **CORS explicit header allowlist:** `Access-Control-Allow-Headers` uses a fixed 14-header allowlist instead of a wildcard. **Federation audience validation:** `validators.rs` blocks cloud metadata endpoints (169.254.169.254, metadata.google.internal), private/loopback CIDRs, `.internal` hostnames, and localhost in production for both federated-token and platform audience/redirect URLs. **Platform cross-org binding:** `upsert_user` enforces `user.org_id == app.org_id` to prevent cross-organization user binding. **Nightly DEK re-wrap:** Re-encrypts secret DEKs under the current primary KEK version so old KMS key versions can be safely destroyed. **HTTP client timeouts:** RPC calls (10s) and Tenderly simulation (30s) enforce timeouts to prevent indefinite hangs. **MCP secret cache:** 5-minute TTL, 1000-entry LRU limit, and periodic cleanup to bound memory. **MCP httpStream rate limiting:** 60 requests per minute per IP on the hosted MCP HTTP streaming transport. **Demo Shroud rate limiting:** `/api/demo/shroud` enforces 10 requests per minute per IP and requires an authenticated session. **x402 payment proof cleanup:** Nightly job deletes `x402_payment_proofs` older than 30 days. **Platform OIDC JWKS SSRF prevention:** `validate_audience_url()` wired into platform app create/update for `oidc_jwks_url` and `resolve_oidc_subject()` defense-in-depth. **DEK re-wrap concurrency guard:** Nightly re-wrap uses `WHERE wrapped_dek = $old` optimistic lock to prevent race conditions. **IPv4-mapped IPv6 bypass fix:** `is_private_or_reserved()` checks `to_ipv4_mapped()`, ULA `fc00::/7`, link-local `fe80::/10`. **Dashboard proxy auth hardening:** Bundler (`/api/bundler`) and demo routes (`/api/demo/vault`, `/api/demo/intents`) require session cookie + per-IP rate limiting; use `x-vercel-forwarded-for`. **Treasury export lockout:** Failed re-auth password increments `failed_login_attempts` and triggers lockout at 10; resets on success. **Signing key path UUID binding:** `validate_signing_key_path` enforces caller agent UUID match on `agents/{uuid}/` paths. **Signing key export re-auth:** `POST /v1/agents/{id}/signing-keys/{chain}/export` requires password re-authentication via `X-Auth-Confirm`; failed re-auth triggers account lockout. **Platform OIDC audience enforcement:** `oidc_audience` column on `platform_apps` (migration 089); enforced in JWT validation when set.

### Webhooks
Event-driven notifications for wallet, proposal, transaction, policy, and signing key events. Webhook delivery is wired end-to-end: `dispatch_event()` calls in treasury_wallets, policies, signing_keys, transactions, and treasury_proposals handlers feed a background worker (`process_pending_deliveries`, every 5s). 12 event types: `wallet.transfer.sent`, `wallet.transfer.received`, `proposal.created/signed/executed/cancelled`, `agent.transaction.broadcast/signed`, `signing_key.rotated`, `policy.created/updated/deleted`. Deliveries use HMAC-SHA256 signatures with 5 retries and exponential backoff. Endpoints: `POST/GET /v1/webhooks` (create/list), `GET/PATCH/DELETE /v1/webhooks/{id}` (manage individual registrations).

### Live Demo
Interactive demo at https://1claw.co/demo — three panels (Vault, Shroud, Intents) with preset buttons, no signup required.

### .env Import
Vault detail page supports bulk secret creation from pasted `.env` file content.

### Embedded Wallets Marketing
Dashboard marketing page at `/embedded-wallets` — showcases embedded wallet capabilities for platform developers: Email OTP passwordless login, social login (Google/Apple/Discord), treasury wallets, wallet spend policies, and "Sign in with 1Claw" OAuth2 flow.

## Agent Onboarding Flows

### Human registers agent (dashboard)
1. Dashboard wizard at /agents/wizard — 3 steps: register agent, save credentials, connect your agent (tabbed code snippets)
2. Or full form at /agents/new with auth method, scopes, guardrails, vault binding

### Human creates vault (dashboard)
1. Dashboard wizard at /vaults/wizard — 3 steps: create vault, store first secret (optional), next steps

### Agent self-enrolls (API/CLI/SDK)
1. `POST /v1/agents/enroll` with `{ name, human_email }` — no auth needed
2. `npx @1claw/cli agent enroll my-agent --email alice@example.com`
3. `AgentsResource.enroll("https://api.1claw.co", { name, human_email })`
4. Human receives credentials by email, creates policies in dashboard
5. Agent exchanges API key for JWT, reads/writes secrets, shares back to human

### MCP configuration (single credential)
```json
{
  "mcpServers": {
    "1claw": {
      "command": "npx",
      "args": ["-y", "@1claw/mcp"],
      "env": {
        "ONECLAW_AGENT_API_KEY": "<agent-api-key>"
      }
    }
  }
}
```

Only `ONECLAW_AGENT_API_KEY` is required. Agent ID and vault are auto-discovered from the token exchange response. Optional overrides: `ONECLAW_AGENT_ID` (explicit agent), `ONECLAW_VAULT_ID` (explicit vault), `ONECLAW_BASE_URL` (default: https://api.1claw.co).

Note: Key-only auth requires agents created or key-rotated after the prefix feature was deployed. Older agents should provide `ONECLAW_AGENT_ID` or rotate their key.

## Fleet Management

For operating dozens or hundreds of agents:
- Batch provisioning via SDK or CLI (`agent create` in a loop)
- Self-enrollment at scale (stagger requests to respect 10-min per-email cooldown)
- Shared vaults with path-scoped policies, or per-agent vaults for isolation
- Vault binding (`vault_ids`) as a second layer of access control
- Transaction guardrails for all Intents API agents
- Audit log filtering by agent ID for monitoring

## Billing

- Free: 1,000 API calls/mo, 10 wallets, 100 signatures
- Pro ($29/mo): 20,000 API calls, 10,000 wallets, 20,000 signatures, Platform API
- Team ($299/mo): 200,000 API calls, 250,000 wallets, 200,000 signatures, SSO, Platform API
- Business ($999/mo): 1,000,000 API calls, wallets, and signatures, CMEK, Intents API, Shroud Enterprise, Treasury Wallets (Shamir MPC)
- Enterprise: Custom, unlimited, KMS delegation, BAA

Overage: prepaid credits or x402 on-chain micropayments on Base. x402 and credit prices are tier-based (see overage_cost_cents). Signature overage after the included monthly quota is a flat per-signature rate (not a % of tx value). 402 response (spec-compliant for x402scan): x402Version, accepts[] with maxAmountRequired (atomic), resource (full URL), payTo, asset, maxTimeoutSeconds, mimeType; unauthenticated paid routes return 402 so scanners can discover. Client pays and retries with X-PAYMENT.

## Scaling & Performance (v0.17)

- **Database**: Configurable pool (default 5 connections/instance). Set `ONECLAW_POOL_DISABLE_STMT_CACHE=1` for Supavisor transaction-mode pooling. Pool stats logged every 30s.
- **Rate limiting**: Two-layer — in-memory L1 + Redis L2 sliding window (`ONECLAW_REDIS_URL`). Both global and auth rate limiters are fully wired to Redis L2 when configured.
- **DEK cache**: 60s TTL DashMap cache for unwrapped DEKs reduces KMS calls ~80%.
- **Usage batching**: Events buffered and batch-inserted every 5s, reducing INSERT/s from thousands to ~1/instance.
- **Manifest endpoint**: ETag/304 support + `?since=` incremental parameter on `/v1/admin/secrets/manifest` for efficient Shroud secret refresh.
- **Nonce serialization**: DB-backed via `POST /v1/admin/nonces/reserve` — Shroud pods no longer use in-memory nonce tracking.
- **Leader election**: Nightly cron jobs use `pg_try_advisory_lock` to avoid duplicate work across instances.
- **Connection pooling**: Shared `reqwest::Client` in AppState for RPC/Stripe/Tenderly reuse.

## Security (v0.22.1 — 2026-05-30 audit fixes + v0.20.4 external audit remediation)

- **Scope validation**: Agent scopes must be glob path patterns (e.g. `secrets/*`), not permission strings like `vault.read`.
- **Error sanitization**: Serde deserialization errors in 400/422 responses are replaced with user-friendly messages.
- **Opaque redaction**: Shroud redaction labels use SHA-256 hash prefix (`[REDACTED:#a1b2c3d4]`) instead of vault paths.
- **JWT revocation on deletion**: Deleting an agent revokes all active JWTs immediately.
- **Idempotency hardening**: `Idempotency-Key` now validates request body hash — mismatched body returns 409 Conflict.
- **Redaction entropy floor**: Secrets shorter than 8 chars or with entropy < 3.0 bits/char are excluded from Shroud automata.
- **Account lockout**: 10 failed login attempts → 15-minute lockout. Session revocation on password change/reset.
- **Signing key export**: Human users can securely export agent signing keys with re-authentication (`X-Auth-Confirm` header).
- **Bootstrap signing keys**: Platform API template `spec.signing_keys` auto-provisions per-chain keys during user bootstrap.
- **Treasury signing delegation verification** (v0.22.1, CRITICAL): Intents API `mode: "treasury"` requires an active delegation; agents without delegation cannot sign using treasury keys.
- **Delegation guardrails enforcement** (v0.22.1): Per-delegation guardrails (`to_allowlist`, `max_value_eth`, `allowed_chains`) now enforced during treasury-mode signing.
- **Webhook SSRF protection** (v0.22.1): Webhook dispatcher validates destination URLs via `validate_audience_url()` and disables redirect following.
- **Treasury send/swap lockout** (v0.22.1): Failed password re-auth on send/swap triggers account lockout at 10 failures.
- **Proposal signer authorization** (v0.22.1): `sign_proposal` verifies caller is a treasury signer or proposal creator.
- **Delegation mode filter** (v0.22.1): Intents API treasury mode only accepts `delegated` or `both` mode delegations.
- **Bankr key vending hardening** (v0.32.2): Deny-by-default policy on `agents/{id}/bankr/*`; agent lease responses and MCP `lease_bankr_key` omit `bk_usr_` (Shroud auto-resolves). Short TTL recommended (300–900 s).
- **Risk Engine (v0.34)**: Adaptive risk scoring on auth events. Detectors: geo-velocity (impossible travel via Haversine), first-seen ASN/country drift, honeytoken canary secrets. Verdicts (low/medium/high/critical, 15-min TTL) gate login — high/critical blocks auth. MaxMind GeoLite2 IP enrichment. API: `GET /v1/risk/events`, `GET /v1/risk/verdicts`, `GET/POST/DELETE /v1/risk/honeytokens`. SDK: `client.risk.*`.
- **DPoP Token Binding (v0.34, RFC 9449)**: JWTs bound to client keypair via `cnf.jkt` claim. Stolen tokens non-replayable without private key. Org setting `dpop_enforcement` (off/warn/required). Continuous Access Evaluation (CAE): critical verdicts auto-revoke all active sessions. SDK: `dpop: true` in config. MCP/CLI: `ONECLAW_DPOP=true` env var.

## MCP Tools (for AI agents)

The MCP server at mcp.1claw.co provides **67 tools** (plus `vault://secrets` resource):
- list_secrets, get_secret, put_secret, delete_secret, describe_secret
- rotate_and_store, rotate_generate, get_env_bundle, list_versions
- create_vault, list_vaults, grant_access, share_secret
- simulate_transaction, simulate_bundle, submit_transaction, sign_transaction
- list_transactions, get_transaction
- list_signing_keys, provision_signing_key, sign_message, sign_typed_data, sign_digest, get_signing_key_balance
- platform_list_apps, platform_create_app, platform_bootstrap_user, platform_reissue_claim, platform_rotate_key, platform_siwe_challenge, platform_get_connection, platform_connection_usage, platform_list_entitlements, platform_preview_template, platform_list_connection_approvals, platform_get_connection_approval, platform_list_connection_pending_approvals, platform_get_connection_spend_policy, platform_get_spend_policy, platform_transfer_ownership, platform_delete_app
- treasury_propose, treasury_sign_proposal, treasury_list_proposals
- order_card, order_gift_card, search_gift_cards, list_cards, get_card_status (reveal intentionally omitted — no PAN in tool output)
- request_approval, list_approvals, get_approval
- lease_bankr_key (privileged — policy-gated; never returns key in tool output)
- execute_http, execute_intent, list_bindings, create_binding, test_binding, list_executions
- inspect_content (works without vault credentials; always available)
- memory_put, memory_get, memory_list, memory_search, delete_memory (agent memory CRUD + semantic search)
- list_automations, trigger_automation (automation management)
- list_runtimes, manage_runtime, runtime_status, runtime_logs (cloud runtime management)
- search_directory (agent discovery directory search)
- send_chat_message, list_chat_conversations (agent chat)
- create_channel, list_channels, send_channel_message (messaging channels)

Configure in Claude Desktop, Cursor, or any MCP-compatible client. Pin `@1claw/mcp@latest` (or a specific version like `@1claw/mcp@0.44.0`). Only `ONECLAW_AGENT_API_KEY` is required — agent ID and vault are auto-discovered.

## Containerized Agent Runtime (`1claw init --docker`, v0.36.0)

`1claw init --docker` provisions a secure agent runtime inside a Docker container in one command. The container ships the 1Claw MCP server and a minimal chat UI and **never receives the agent API key or any LLM provider key** — the host daemon injects credentials over a Unix-socket mount (the same trust boundary as local daemon mode).

- **Cloud mode (default):** provisions an agent (Shroud + Intents API enabled) + vault + read policies on `secrets/*` and `providers/*`, stores the agent key in the local CLI vault, and wires the chat UI to an LLM **through Shroud** (`mode=cloud`).
- **`--local`:** fully offline — no cloud account, no LLM. Only `/help`, `/secrets`, `/info`, `/proxy` slash commands.
- **Modules:** `--module=ampersend,onchain,langchain,elizaos,scaffold-agent` compose container extensions from bundled `module.yaml` manifests; `--list-modules` prints the catalog.
- **Management:** `1claw containers list|info|stop|rm|logs`; `1claw publish` (rebuild + push); `1claw eject` (Dockerfile + docker-compose); `1claw deploy --google-cloud` (Terraform for Cloud Run + Secret Manager).

**Chat LLM through Shroud — three provider-key sources** (container never holds the key; Shroud resolves in order):
1. **1Claw LLM Token Billing** (default, no key): enable for the org; Shroud routes via the Stripe AI Gateway.
2. **1Claw cloud vault:** `--llm-api-key <key>` (default `--llm-key-store cloud`) stores at `providers/<provider>/api-key`; Shroud auto-fetches with the agent JWT.
3. **Local CLI vault (BYOK):** `--llm-api-key <key> --llm-key-store local` or `--llm-api-key-secret <name>`; the daemon injects it as the `X-Shroud-Api-Key` header.

Model selection: `--llm-provider` (default `openai`), `--llm-model` (default per provider, e.g. `gpt-4o-mini`). Local-vault recovery: `1claw local destroy --force` / `1claw local reset`.

<!-- AUTO-GENERATED-DOC-INDEX:START -->
## Documentation index

Complete index of 174 doc pages on docs.1claw.co. Full content: https://docs.1claw.co/llms-full.txt

### Introduction (1)

- [Introduction](https://docs.1claw.co/docs/intro)

### Quickstart (3)

- [Quickstart for agents](https://docs.1claw.co/docs/quickstart/agents)
- [Quickstart for humans](https://docs.1claw.co/docs/quickstart/humans)
- [Quickstart](https://docs.1claw.co/docs/quickstart)

### Concepts (7)

- [HSM architecture](https://docs.1claw.co/docs/concepts/hsm-architecture)
- [Human vs Agent API](https://docs.1claw.co/docs/concepts/human-vs-agent-api)
- [Licensing](https://docs.1claw.co/docs/concepts/licensing)
- [Parts of 1claw](https://docs.1claw.co/docs/concepts/parts-of-1claw)
- [Secrets model](https://docs.1claw.co/docs/concepts/secrets-model)
- [Trust model](https://docs.1claw.co/docs/concepts/trust-model)
- [What is 1claw?](https://docs.1claw.co/docs/concepts/what-is-1claw)

### Guides (25)

- [Agent Environment Tagging](https://docs.1claw.co/docs/guides/agent-environment-tagging)
- [Audit and compliance](https://docs.1claw.co/docs/guides/audit-and-compliance)
- [Billing & Usage](https://docs.1claw.co/docs/guides/billing-and-usage)
- [Deploying Updates](https://docs.1claw.co/docs/guides/deploying-updates)
- [Email Notifications](https://docs.1claw.co/docs/guides/email-notifications)
- [Advanced Embedded Wallet Features](https://docs.1claw.co/docs/guides/embedded-wallets/advanced)
- [Embedded Wallet Authentication](https://docs.1claw.co/docs/guides/embedded-wallets/authentication)
- [Fiat On and Off Ramps](https://docs.1claw.co/docs/guides/embedded-wallets/fiat-ramps)
- [Getting Started with Embedded Wallets](https://docs.1claw.co/docs/guides/embedded-wallets/getting-started)
- [Multi-Chain Embedded Wallets](https://docs.1claw.co/docs/guides/embedded-wallets/multi-chain-wallets)
- [Embedded Wallets Overview](https://docs.1claw.co/docs/guides/embedded-wallets/overview)
- [Platform API for Embedded Wallets](https://docs.1claw.co/docs/guides/embedded-wallets/platform-api)
- [React Integration](https://docs.1claw.co/docs/guides/embedded-wallets/react-integration)
- [Security and Custody](https://docs.1claw.co/docs/guides/embedded-wallets/security-and-custody)
- [Send, Swap, and Receive](https://docs.1claw.co/docs/guides/embedded-wallets/send-swap-receive)
- [Wallet Spend Policies](https://docs.1claw.co/docs/guides/embedded-wallets/spend-policies)
- [Testing and Production](https://docs.1claw.co/docs/guides/embedded-wallets/testing-production)
- [Wallet Access Policies](https://docs.1claw.co/docs/guides/embedded-wallets/wallet-access-policies)
- [Environment Variables](https://docs.1claw.co/docs/guides/environment-variables)
- [5-minute walkthrough: vault, key, transaction](https://docs.1claw.co/docs/guides/five-minute-walkthrough)
- [Policy Engine v2](https://docs.1claw.co/docs/guides/policy-engine-v2)
- [Principal-Type Audit](https://docs.1claw.co/docs/guides/principal-type-audit)
- [Setup by client](https://docs.1claw.co/docs/guides/setup-by-client)
- [Troubleshooting](https://docs.1claw.co/docs/guides/troubleshooting)
- [x402 Micropayments](https://docs.1claw.co/docs/guides/x402)

### SDKs (5)

- [curl examples](https://docs.1claw.co/docs/sdks/curl-examples)
- [Go SDK](https://docs.1claw.co/docs/sdks/go)
- [JavaScript / TypeScript SDK](https://docs.1claw.co/docs/sdks/javascript)
- [SDKs overview](https://docs.1claw.co/docs/sdks/overview)
- [Python SDK](https://docs.1claw.co/docs/sdks/python)

### Security (13)

- [Agent keys](https://docs.1claw.co/docs/security/agent-keys)
- [Audit Hash Chain Verification](https://docs.1claw.co/docs/security/audit-verification)
- [Compliance](https://docs.1claw.co/docs/security/compliance)
- [HSM overview](https://docs.1claw.co/docs/security/hsm-overview)
- [Human Factor Auth (HFA)](https://docs.1claw.co/docs/security/human-factor-auth)
- [Key hierarchy](https://docs.1claw.co/docs/security/key-hierarchy)
- [Policy Schema Versioning](https://docs.1claw.co/docs/security/policy-versioning)
- [1Claw Security Overview](https://docs.1claw.co/docs/security/security-overview)
- [Trust Model Comparison: 1Claw vs Signing-Only Infrastructure](https://docs.1claw.co/docs/security/trust-model-comparison)
- [Two-factor authentication](https://docs.1claw.co/docs/security/two-factor-auth)
- [1Claw Security Architecture Whitepaper](https://docs.1claw.co/docs/security/whitepaper)
- [Why 1Claw for Embedded Wallets](https://docs.1claw.co/docs/security/why-1claw-embedded-wallets)
- [Zero trust](https://docs.1claw.co/docs/security/zero-trust)

### Reference (9)

- [API & MCP Testing](https://docs.1claw.co/docs/reference/api-mcp-testing)
- [API reference](https://docs.1claw.co/docs/reference/api-reference)
- [Changelog 2026](https://docs.1claw.co/docs/reference/changelog-2026)
- [Changelog](https://docs.1claw.co/docs/reference/changelog)
- [Error codes](https://docs.1claw.co/docs/reference/error-codes)
- [Glossary](https://docs.1claw.co/docs/reference/glossary)
- [Rate limits](https://docs.1claw.co/docs/reference/rate-limits)
- [Request pipeline](https://docs.1claw.co/docs/reference/request-pipeline)
- [Shroud supported models](https://docs.1claw.co/docs/reference/shroud-supported-models)

### Integrations (27)

- [Agent discovery & machine-readable metadata](https://docs.1claw.co/docs/integrations/agent-discovery)
- [Agent frameworks (Eliza, GOAT, LangChain, CrewAI)](https://docs.1claw.co/docs/integrations/agent-frameworks)
- [Add an agent template](https://docs.1claw.co/docs/integrations/agent-templates)
- [Vercel AI SDK and OpenAI Agents SDK](https://docs.1claw.co/docs/integrations/ai-sdk-integration)
- [Base MCP, Secured](https://docs.1claw.co/docs/integrations/base-mcp-secure)
- [Setup 1claw with Claude Code](https://docs.1claw.co/docs/integrations/claude-code)
- [CLI](https://docs.1claw.co/docs/integrations/cli)
- [Coinbase Wallet and Smart Wallet](https://docs.1claw.co/docs/integrations/coinbase-smart-wallet)
- [CrewAI integration](https://docs.1claw.co/docs/integrations/crewai)
- [Ecosystem & Integrations](https://docs.1claw.co/docs/integrations/ecosystem)
- [elizaOS plugin](https://docs.1claw.co/docs/integrations/elizaos)
- [Fireblocks integration](https://docs.1claw.co/docs/integrations/fireblocks)
- [GitHub Action](https://docs.1claw.co/docs/integrations/github-action)
- [LangChain integration](https://docs.1claw.co/docs/integrations/langchain)
- [Magic integration](https://docs.1claw.co/docs/integrations/magic)
- [MCP for AI coding tools](https://docs.1claw.co/docs/integrations/mcp-deep-dive)
- [MCP integration](https://docs.1claw.co/docs/integrations/mcp-integration)
- [Migrate from Dynamic](https://docs.1claw.co/docs/integrations/migrate-from-dynamic)
- [Migrate from Privy](https://docs.1claw.co/docs/integrations/migrate-from-privy)
- [Migrate From Turnkey to 1Claw](https://docs.1claw.co/docs/integrations/migrate-from-turnkey)
- [1claw OpenClaw Plugin](https://docs.1claw.co/docs/integrations/openclaw-plugin)
- [Using 1claw with OpenClaw](https://docs.1claw.co/docs/integrations/openclaw)
- [Integrations overview](https://docs.1claw.co/docs/integrations/overview)
- [Scaffold-Agent](https://docs.1claw.co/docs/integrations/scaffold-agent)
- [Thirdweb integration](https://docs.1claw.co/docs/integrations/thirdweb)
- [wagmi + RainbowKit integration](https://docs.1claw.co/docs/integrations/wagmi-rainbowkit)
- [Web3Auth integration](https://docs.1claw.co/docs/integrations/web3auth)

### Treasury Policy (11)

- [Account Abstraction (ERC-4337)](https://docs.1claw.co/docs/treasury/account-abstraction)
- [Human-in-the-loop approvals](https://docs.1claw.co/docs/treasury/approvals)
- [Embedded Wallets — 2-Minute Quickstart](https://docs.1claw.co/docs/treasury/embedded-wallets)
- [Treasury Wallets](https://docs.1claw.co/docs/treasury/overview)
- [Policy Engine — Cedar, OPA & Consensus](https://docs.1claw.co/docs/treasury/policy-engine)
- [Policy cookbooks](https://docs.1claw.co/docs/treasury/policy-examples)
- [Policy language](https://docs.1claw.co/docs/treasury/policy-language)
- [Safe (Gnosis Safe) integration](https://docs.1claw.co/docs/treasury/safe-multisig)
- [Treasury Spend Policies](https://docs.1claw.co/docs/treasury/spend-policies)
- [Wallet Access Policies](https://docs.1claw.co/docs/treasury/wallet-access-policies)
- [@1claw/wallet-react](https://docs.1claw.co/docs/treasury/wallet-react)

### Other (73)

- [Audit log (agents)](https://docs.1claw.co/docs/agents/api/audit-log)
- [Agent authentication](https://docs.1claw.co/docs/agents/api/authentication)
- [Agent API errors](https://docs.1claw.co/docs/agents/api/errors)
- [Fetch a secret](https://docs.1claw.co/docs/agents/api/fetch-secret)
- [List accessible secrets](https://docs.1claw.co/docs/agents/api/list-accessible-secrets)
- [Agent API overview](https://docs.1claw.co/docs/agents/api/overview)
- [Bankr Key Vending](https://docs.1claw.co/docs/agents/bankr-keys)
- [Browser Bridge](https://docs.1claw.co/docs/agents/browser-bridge)
- [Messaging Channels](https://docs.1claw.co/docs/agents/channels)
- [Agent Communication — Chat & Channels](https://docs.1claw.co/docs/agents/communication)
- [Connectors](https://docs.1claw.co/docs/agents/connectors)
- [Agent-to-Agent Delegation](https://docs.1claw.co/docs/agents/delegation)
- [Agent Discovery](https://docs.1claw.co/docs/agents/discovery)
- [Managing Agent Fleets](https://docs.1claw.co/docs/agents/fleet-management)
- [Guardrail governance](https://docs.1claw.co/docs/agents/guardrail-governance)
- [Crypto Transaction Proxy (moved)](https://docs.1claw.co/docs/agents/intents/crypto-proxy-legacy)
- [Intents API — Guardrails & Security](https://docs.1claw.co/docs/agents/intents/guardrails)
- [Multi-Chain Signing](https://docs.1claw.co/docs/agents/intents/multi-chain-signing)
- [Intents API](https://docs.1claw.co/docs/agents/intents/overview)
- [Intents API — Signing](https://docs.1claw.co/docs/agents/intents/signing)
- [Agent Memory](https://docs.1claw.co/docs/agents/memory)
- [OIDC federation — use 1claw as an IdP for Anthropic WIF](https://docs.1claw.co/docs/agents/oidc-federation)
- [Agents overview](https://docs.1claw.co/docs/agents/overview)
- [Agent Safe accounts (Phase 5)](https://docs.1claw.co/docs/agents/safe-accounts)
- [Agent Self-Onboarding](https://docs.1claw.co/docs/agents/self-enrollment)
- [Shroud Configuration & Operations](https://docs.1claw.co/docs/agents/shroud/configuration)
- [IDE & tool setup (Shroud proxy)](https://docs.1claw.co/docs/agents/shroud/ide-setup)
- [Shroud](https://docs.1claw.co/docs/agents/shroud/overview)
- [Shroud Threat Detection](https://docs.1claw.co/docs/agents/shroud/threat-detection)
- [Automations](https://docs.1claw.co/docs/automations/overview)
- [Payment Cards](https://docs.1claw.co/docs/cards/overview)
- [Agents & policies](https://docs.1claw.co/docs/dashboard/agents-policies)
- [Dashboard overview](https://docs.1claw.co/docs/dashboard/overview)
- [Platform wizard](https://docs.1claw.co/docs/dashboard/platform-wizard)
- [Settings & billing](https://docs.1claw.co/docs/dashboard/settings-billing)
- [Treasury & cards](https://docs.1claw.co/docs/dashboard/treasury-cards)
- [Vaults & secrets](https://docs.1claw.co/docs/dashboard/vaults-secrets)
- [Platform API (multi-tenant)](https://docs.1claw.co/docs/platform-api/multi-tenant)
- [OAuth Connected Accounts](https://docs.1claw.co/docs/platform-api/oauth-connections)
- [Platform API](https://docs.1claw.co/docs/platform-api/overview)
- [Webhooks](https://docs.1claw.co/docs/platform-api/webhooks)
- [Risk Engine](https://docs.1claw.co/docs/risk-engine/overview)
- [Runtime Hosting](https://docs.1claw.co/docs/runtimes/hosting)
- [Cloud Runtimes](https://docs.1claw.co/docs/runtimes/overview)
- [Sharing Secrets](https://docs.1claw.co/docs/sharing/overview)
- [Customer-Managed Encryption Keys (CMEK)](https://docs.1claw.co/docs/vaults/cmek)
- [Give an agent access](https://docs.1claw.co/docs/vaults/golden-path)
- [Deactivate agent / Rotate key](https://docs.1claw.co/docs/vaults/human-api/agents/deactivate-agent)
- [List agents](https://docs.1claw.co/docs/vaults/human-api/agents/list-agents)
- [Register an agent](https://docs.1claw.co/docs/vaults/human-api/agents/register-agent)
- [Authentication](https://docs.1claw.co/docs/vaults/human-api/authentication)
- [Human API errors](https://docs.1claw.co/docs/vaults/human-api/errors)
- [Create a policy (grant)](https://docs.1claw.co/docs/vaults/human-api/grants/create-grant)
- [List policies (grants)](https://docs.1claw.co/docs/vaults/human-api/grants/list-grants)
- [Revoke a policy (grant)](https://docs.1claw.co/docs/vaults/human-api/grants/revoke-grant)
- [Human API overview](https://docs.1claw.co/docs/vaults/human-api/overview)
- [Create or update a secret](https://docs.1claw.co/docs/vaults/human-api/secrets/create)
- [Delete a secret](https://docs.1claw.co/docs/vaults/human-api/secrets/delete)
- [Read a secret](https://docs.1claw.co/docs/vaults/human-api/secrets/read)
- [Rotate a secret](https://docs.1claw.co/docs/vaults/human-api/secrets/rotate)
- [Update a secret (new version)](https://docs.1claw.co/docs/vaults/human-api/secrets/update)
- [MCP Deployment](https://docs.1claw.co/docs/vaults/mcp/deployment)
- [MCP Server Overview](https://docs.1claw.co/docs/vaults/mcp/overview)
- [MCP Security](https://docs.1claw.co/docs/vaults/mcp/security)
- [MCP Setup Guide](https://docs.1claw.co/docs/vaults/mcp/setup)
- [MCP Tool Reference](https://docs.1claw.co/docs/vaults/mcp/tools)
- [Multi-Party Computation (MPC)](https://docs.1claw.co/docs/vaults/mpc)
- [Vaults overview](https://docs.1claw.co/docs/vaults/overview)
- [Revoking access](https://docs.1claw.co/docs/vaults/revoking-access)
- [Rotating secrets](https://docs.1claw.co/docs/vaults/rotating-secrets)
- [Secret rotation and bindings](https://docs.1claw.co/docs/vaults/rotation-bindings)
- [Scoped permissions](https://docs.1claw.co/docs/vaults/scoped-permissions)
- [Securing Agent Access](https://docs.1claw.co/docs/vaults/securing-access)

<!-- AUTO-GENERATED-DOC-INDEX:END -->