---
title: "Set an agent's payment guardrails"
method: PATCH
path: "/v1/agents/{agent_id}/pay/settings"
tags: ["Pay"]
---

# Set an agent's payment guardrails

`PATCH /v1/agents/{agent_id}/pay/settings`

## Request

- Base URL: `https://api.1claw.co`
- URL: `https://api.1claw.co/v1/agents/{agent_id}/pay/settings`
- Auth: HTTP bearer

Human owners and admins only. These are the numbers every payment
decision is measured against: the per-payment cap, the daily limit,
the recipient allowlist, whether a passkey is required at all, and
whether the agent may hold a spending grant. An agent that could set
them would be setting its own ceiling.

Omitted fields are left alone; `null` clears a cap, the allowlist or
the grant TTL. A change that widens anything (raising or clearing a
cap, turning pay or grant mode on, turning a passkey or approval
requirement off, a longer grant TTL, or naming a recipient that is not
already on the allowlist) needs `X-Auth-Confirm` with a re-auth token
for purpose `security.agent_pay_guardrails.widen` (strong factor: a
password is refused once a passkey or TOTP is enrolled). Tightening
needs no step-up. Audited `agent.pay_guardrails_updated`.

No allowlist is not a wildcard: `null` and `[]` are enforced alike, so
an agent with `pay_require_passkey: false` and no allowlist can pay no
one unattended.

## Path parameters

- `agent_id` string, uuid, required

## Headers

- `X-Auth-Confirm` string

## Request body

- UpdatePayGuardrailsRequest
  - `pay_enabled` boolean
  - `pay_max_usd` string, nullable
  - `pay_daily_limit_usd` string, nullable
  - `pay_payto_allowlist` string[], nullable: Recipients an unattended agent may pay. Null is not a wildcard: it is enforced exactly like `[]`, so for an unattended agent it means no one. An agent that requires a passkey or an approval can pay any recipient a person approves, payment by payment.
  - `pay_require_passkey` boolean: Defaults true. Turning it off is what "unattended" means.
  - `pay_require_approval` boolean
  - `pay_grant_mode_enabled` boolean
  - `pay_grant_max_usd` string, nullable
  - `pay_grant_max_ttl_secs` integer, nullable

## Response `200`

Updated guardrails

## Other responses

- `403`: Not a human caller, not an owner or admin, or a widening change without a valid step-up token

---

[API](https://skmtc.dev/1claw/apis/1claw-api.md) · [All operations](https://skmtc.dev/1claw/apis/1claw-api/llms.txt) · [OpenAPI document](https://skmtc.dev/1claw/apis/1claw-api/revisions/5fa0918f3b41?raw)