> ## Documentation Index
> Fetch the complete documentation index at: https://docs.natural.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Use REST only for unsupported languages or when the user explicitly requests raw HTTP.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.

# Set limits

> Limit how much each agent can move per transaction, per day, and per month

Cap how much you and each of your agents can move per transaction, per day, and per month. For how the levels combine, read the [Limits overview](/guides/concepts/limits).

<Snippet file="shared/prerequisites.mdx" />

Each limit applies to a single payment (`perTransaction`), a UTC calendar day (`perDay`), or a calendar month (`perMonth`).

<Note>
  A limit never automatically fails a payment. A payment that breaches a limit returns a normal
  `2xx`, no money moves, and it **holds as an approval** until someone approves or denies it. See
  [Approve or deny a held payment](/guides/controls/approvals).
</Note>

## Account limits

Your account limits are the backstop over everything you and every agent do.

### Read your limits

[`GET /parties/me/limits`](/api-reference/parties/get-party-approval-limits) returns the current limits. When no limit is set, `limits` is `null`.

<CodeGroup>
  ```python Python theme={null}
  limits = client.parties.get_limits()
  ```

  ```typescript TypeScript theme={null}
  const limits = await client.parties.getLimits();
  ```

  ```bash CLI theme={null}
  natural parties get-limits
  ```

  ```text MCP theme={null}
  What are my account spending limits?
  ```

  ```bash cURL theme={null}
  curl https://api.natural.com/parties/me/limits \
    -H "Authorization: Bearer $NATURAL_API_KEY"
  ```
</CodeGroup>

<Snippet file="api-examples/parties.getLimits.response.mdx" />

### Set your limits

[`PUT /parties/me/limits`](/api-reference/parties/set-party-approval-limits) replaces all three windows at once. It requires `party.update`; agent keys cannot call it.

<CodeGroup>
  ```python Python theme={null}
  limits = client.parties.set_limits(
      per_transaction=250_000,  # $2,500 per payment
      per_day=1_000_000,        # $10,000 per day
      per_month=None,           # no monthly limit
  )
  ```

  ```typescript TypeScript theme={null}
  const limits = await client.parties.setLimits({
    perTransaction: 250_000, // $2,500 per payment
    perDay: 1_000_000, // $10,000 per day
    perMonth: null, // no monthly limit
  });
  ```

  ```bash CLI theme={null}
  natural parties set-limits --per-transaction 250000 --per-day 1000000
  ```

  ```bash cURL theme={null}
  curl -X PUT https://api.natural.com/parties/me/limits \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "attributes": {
          "perTransaction": 250000,
          "perDay": 1000000,
          "perMonth": null
        }
      }
    }'
  ```
</CodeGroup>

<Snippet file="api-examples/parties.setLimits.response.mdx" />

### Remove all limits

[`DELETE /parties/me/limits`](/api-reference/parties/disable-party-approval-limits) clears every window in one call. To clear just one window, `PUT` that window as `null` and keep the others. Removing your account limits does not touch an agent's own limits or a limit a customer set on your agent; clear those where you set them.

<CodeGroup>
  ```python Python theme={null}
  client.parties.disable_limits()
  ```

  ```typescript TypeScript theme={null}
  await client.parties.disableLimits();
  ```

  ```bash CLI theme={null}
  natural parties disable-limits
  ```

  ```bash cURL theme={null}
  curl -X DELETE https://api.natural.com/parties/me/limits \
    -H "Authorization: Bearer $NATURAL_API_KEY"
  ```
</CodeGroup>

## Agent limits

Give one agent (`agt_*`) a tighter budget than the rest of your account. Set limits when you [create the agent](/guides/agents/create-agent) with `limits` on [`POST /agents`](/api-reference/agents/create-agent). To change them afterward, [`PATCH /agents/{agentId}`](/api-reference/agents/update-agent).

`limits` is a **full replacement**: sending it resets every window to what you pass.

<CodeGroup>
  ```python Python theme={null}
  import uuid

  agent = client.agents.update(
      "agt_019cd1798d637a4da75dce386343931d",
      idempotency_key=str(uuid.uuid4()),
      limits={"per_transaction": 100_000},  # $1,000; clears perDay and perMonth
  )
  ```

  ```typescript TypeScript theme={null}
  const agent = await client.agents.update({
    agentId: "agt_019cd1798d637a4da75dce386343931d",
    idempotencyKey: crypto.randomUUID(),
    limits: { perTransaction: 100_000 }, // $1,000; clears perDay and perMonth
  });
  ```

  ```bash CLI theme={null}
  natural agents update --agent-id agt_019cd1798d637a4da75dce386343931d \
    --idempotency-key "$(uuidgen)" \
    --json '{"limits": {"perTransaction": 100000}}'
  ```

  ```bash cURL theme={null}
  curl -X PATCH https://api.natural.com/agents/agt_019cd1798d637a4da75dce386343931d \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "attributes": {
          "limits": { "perTransaction": 100000 }
        }
      }
    }'
  ```
</CodeGroup>

<Snippet file="api-examples/agents.update.response.mdx" />

## How limits compose

A payment can pass through several limits: your **account** limit, the **agent** limit, and limits set by your customer. They are independent gates with no precedence: every applicable one must clear, so in effect the tightest limit wins.

| Level | Limits | Set by |
| - | - | - |
| **Account** | `perTransaction`, `perDay`, `perMonth` | You, for your whole account |
| **Agent** | `perTransaction`, `perDay`, `perMonth` | You, per agent |
| **On a customer's behalf** | `perTransaction` only | A customer, when they authorize your agent |

A payment that breaches any limit holds for [approval](/guides/controls/approvals). All limits must clear or be approved for a payment to complete.

<Snippet file="shared/webhook-approval.mdx" />


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.