Update an agent
Human users only. Control-plane consensus on agent.update runs first: when the org requires it the call answers 202 pending_approval, and the same PATCH with approval_id set to the approved pending_approval_id proceeds.
A change to any transaction guardrail needs a step-up: X-Auth-Confirm with a re-auth token for purpose security.guardrail.edit or the account password. Since 2026-10-18 that includes raw_signing_enabled and raw_signing_policy, because blind signing bypasses every other guardrail; before, enabling it was a plain agent.update. The step-up applies whenever the value actually changes, tightening included. A widening (turning raw signing on, or moving raw_signing_policy from deny toward approve or allow) is queued for human approval when the org requires approval for guardrail changes: the call answers 202 awaiting_approval and the change is applied by the server when that approval is approved. Spend-cap fields record a revision and can queue, but do not need the step-up.
Request
- Base URL: https://api.1claw.co
- URL: https://api.1claw.co/v1/agents/{agent_id}
- Auth: HTTP bearer
Path parameters
Headers
Required when the request changes a transaction guardrail, including raw_signing_enabled and raw_signing_policy: a re-auth token for purpose security.guardrail.edit, or the account password.
Request body
Smart account address associated with this agent.
Chain name for the smart account.
EVM chain id for the smart account.
Smart account deployment nonce.
Smart account initialisation data.
Allow this agent to sign arbitrary messages.
EIP-712 domains this agent may sign under.
Default policy applied to EIP-712 signing requests.
Allow this agent to sign raw digests (blind signing; bypasses transaction guardrails). A change needs the guardrail step-up (X-Auth-Confirm, purpose security.guardrail.edit); turning it on is a widening and queues when the org requires approval for guardrail changes.
Default LLM provider for automations and Shroud.
Default LLM model for automations and Shroud.
List this agent in the cross-org agent directory.
Description shown on the public directory listing.
Tags shown on the public directory listing.
Enable durable key-value and semantic memory for this agent. Required before PUT /v1/agents/{agent_id}/memory/{namespace}/{key} will accept a write; without it that endpoint returns 403.
Namespaces this agent may use. Empty or omitted means unrestricted.
Maximum size of a single memory entry value. Null uses the platform default (64 KiB).
Maximum value per transaction in native major units for the transacting chain family (ETH on EVM, BTC on Bitcoin, SOL on Solana, XRP, ADA, TRX).
Rolling daily spend cap in native major units, enforced per chain family at signing time.
Deprecated alias for tx_max_value. Same unit semantics (native major units, not ETH-only).
Deprecated alias for tx_daily_limit.
Enable/disable Shroud LLM Proxy
Default system prompt for agent chat (null clears).
Enable/disable Execution Intents for this agent
Guardrails applied to all execution intents for this agent
When true, transaction/sign requests must arrive via a TEE host (Pro+ only)
When true, execute requests must arrive via TEE and all direct secret reads are blocked (Pro+ only)
Max transactions per UTC calendar day. Null = unlimited.
Per-chain daily overhead budget in native units.
Solana wallet addresses whose ATAs may be created.
Whether this agent may order payment cards (x402 card ordering). Pro+ tier.
Maximum USD amount for a single card order. null clears.
Maximum cumulative USD spent ordering cards per rolling 24h window. null clears.
One cap across ALL of this agent's x402 stablecoin spend — POST /v1/pay and card orders together. Calendar day, UTC. null clears it. Applied in addition to the per-route caps, never instead of them: tx_* bounds signing and submitting, pay_* bounds POST /v1/pay, and card_* bounds card orders. None of those three bounds the others, so this is the only field that caps an agent's total stablecoin spend.
Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients).
Whether agents may reveal card details subject to per-card reveal policy.
When true, card orders route through the human approval queue before x402 payment.
Graduated transaction approval policy (HITL thresholds).
Which business actions this agent must ask a human about, and above what amount. {} means no per-action rules.
Shape: { "default_mode": "deny|approve|allow", "rules": [ { "action_type": "refund.create", "mode": "approve", "require_for_amount_above_usd": "50", "summary_template": "Refund {{amount_usd}} to {{customer_email}}" } ] }.
A rule can only raise the bar. Editing this is classified as a guardrail widening, so it routes through the same approval flow as loosening a transaction limit. Malformed rules are rejected on write rather than ignored at request time.
EIP-712 escalation policy.
Simulation failure escalation policy.
Block unlimited ERC-20 approvals (max uint256 / setApprovalForAll).
Max transactions to the same recipient per UTC day. Null clears.
Max native spend to same recipient per UTC day. Null clears.
First-time recipient native cap. Null clears.
Per-tx USD cap. Null clears.
Rolling 24h USD spend cap. Null clears.
Raw digest signing policy. A change needs the guardrail step-up (X-Auth-Confirm, purpose security.guardrail.edit); moving toward allow is a widening and queues when the org requires approval for guardrail changes.
personal_sign guardrails JSON.
Allow ERC-4337 gasless UserOperations.
Allow EIP-7702 (tx type 4).
When true, clears circuit-breaker auto-suspension (human owner/admin only).
Enable OIDC federation (RFC 8693 token-exchange) for this agent. When true, the agent may call POST /v1/auth/federated-token to mint federation tokens for the audiences listed in federation_audiences.
Allowlist of aud values the federation token-exchange may issue tokens for (e.g. ["https://api.anthropic.com"]). Empty array blocks all federation requests (zero-trust default).
Per-agent TTL override for federation tokens (seconds). NULL falls back to the global default (ONECLAW_JWT_FEDERATED_TOKEN_EXPIRY_SECS). Hard-capped at 3600 seconds.
Token contract/mint addresses this agent may interact with. Empty = unrestricted.
When true, only tokens in the known_tokens registry may be used.
Allowed XRP Ledger transaction types (Payment, TrustSet, etc.). Empty = all allowed.
Per-chain guardrail overrides. Keys are signing chains (ethereum, bitcoin, solana, xrp, cardano, tron). Each value may include max_value, daily_limit, to_allowlist, token_allowlist (legacy *_eth keys accepted), max_fee_per_gas_gwei, max_gas_limit, gas_daily_budget_native (UTC-day cumulative EVM gas in native units). Strictest of global and per-chain limits wins. Daily limits apply per chain family spend, not cross-chain totals.
Optional expiration time for the agent's API key. Set to null to clear.
Named environment for this agent (production, preview, development, or custom).
When true, the environment tag cannot be changed after creation.
When true, env var resolve endpoints auto-fill environment from this agent's tag.
Per-environment guardrail overrides keyed by environment slug.
Recipient address screening policy. mode may be off, deny, or approve.
Completes a control-plane consensus gate on agent.update: the pending_approval_id of an earlier 202, once approved. It does not apply a queued guardrail widening and cannot bypass the widening queue: a queued widening is applied by the server when its approval is approved, with nothing to resubmit.
Response
Agent updated
A child is a sub-agent under parent_agent_id that inherits its parent's policies and does not count against the plan's agent cap.
Present on child agents.
Whether durable key-value and semantic memory is enabled. Omitted when false: the server skips serializing this field unless it is true, so an absent key means disabled.
Namespaces this agent may use. Omitted when empty, which means unrestricted.
Maximum size of a single memory entry value. Omitted when unset, which means the platform default (64 KiB).
Maximum value per transaction in native major units for the transacting chain family (ETH on EVM, BTC on Bitcoin, SOL on Solana, XRP, ADA, TRX).
Rolling daily spend cap in native major units, enforced per chain family at signing time.
Deprecated alias for tx_max_value. Same unit semantics (native major units, not ETH-only).
Deprecated alias for tx_daily_limit.
Sum of today's spend across all chain families in major units. Prefer tx_spent_today_by_chain.
Deprecated alias for tx_spent_today.
SHA-256 fingerprint of the client certificate (mTLS agents)
OIDC issuer URL (oidc_client_credentials agents)
OIDC client ID (oidc_client_credentials agents)
Ed25519 SSH public key (base64-encoded, auto-generated at creation)
P-256 ECDH public key (base64 SEC1 uncompressed point, auto-generated at creation)
Whether this agent routes LLM traffic through the Shroud TEE proxy
Default system prompt for agent chat when requests do not override it.
Whether Execution Intents (bindings and execute endpoint) are enabled for this agent
Guardrails applied to all execution intents for this agent
When true, transaction/sign requests must arrive via a TEE host (Pro+ only)
When true, execute requests must arrive via TEE and all direct secret reads are blocked (Pro+ only)
Max transactions per UTC calendar day. Null = unlimited.
Per-chain daily overhead budget in native units.
Solana wallet addresses whose ATAs may be created.
Whether this agent may order payment cards (x402 card ordering).
Maximum USD amount for a single card order.
Maximum cumulative USD spent ordering cards per rolling 24h window.
One cap across ALL of this agent's x402 stablecoin spend — POST /v1/pay and card orders together. Calendar day, UTC. Omit for no cap. Applied in addition to the per-route caps, never instead of them: tx_* bounds signing and submitting, pay_* bounds POST /v1/pay, and card_* bounds card orders. None of those three bounds the others, so this is the only field that caps an agent's total stablecoin spend.
Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients).
Whether agents may reveal card details subject to per-card reveal policy.
When true, card orders route through the human approval queue before x402 payment.
Graduated transaction approval policy (HITL thresholds).
Which business actions this agent must ask a human about, and above what amount. {} means no per-action rules.
Shape: { "default_mode": "deny|approve|allow", "rules": [ { "action_type": "refund.create", "mode": "approve", "require_for_amount_above_usd": "50", "summary_template": "Refund {{amount_usd}} to {{customer_email}}" } ] }.
A rule can only raise the bar. Editing this is classified as a guardrail widening, so it routes through the same approval flow as loosening a transaction limit. Malformed rules are rejected on write rather than ignored at request time.
Block unlimited ERC-20 approvals.
True when circuit breaker auto-suspended the agent after repeated guardrail denials.
Today's transaction count (UTC calendar day). Present when intents_api_enabled.
Today's overhead spend by chain in native units.
Whether this agent may mint OIDC federation tokens via POST /v1/auth/federated-token. False by default.
Allowlist of audience URIs the agent may federate to.
Per-agent TTL override for federation tokens (60..=3600).
Chains for which this agent has provisioned signing keys.
JSON array of allowed EIP-712 domain entries.
Default EIP-712 policy (deny blocks all unless allowlisted).
Whether EIP-191 personal_sign is enabled.
Whether the raw/precomputed-digest signing intent (eip712_digest) is enabled. Blind signing — bypasses transaction guardrails; OFF by default and human-set. Required for ERC-1271/ERC-7739 flows (e.g. Polymarket).
Token contract/mint addresses this agent may interact with.
When true, only tokens in the known_tokens registry may be used.
Allowed XRP Ledger transaction types.
Per-chain guardrail overrides.
Per-chain-family daily spend in native major units (keys: evm, bitcoin, solana, xrp, cardano, tron).
Optional expiration time for the agent's API key.
Agent's Ethereum EOA address (used as Safe signer for smart accounts and Intents API).
Named environment this agent belongs to (production, preview, development, or custom).
When true, the environment tag is locked and cannot be changed.
When true, env var resolve endpoints auto-fill environment from this agent's tag.
Per-environment guardrail overrides keyed by environment slug.
Recipient address screening policy. mode may be off, deny, or approve.
Changes
No recorded changes to this operation across all 1 revision of this API.