> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nebulaonchain.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure Spending Limits and Policy for Your Agent
> Set per-transaction and daily USDC spending caps, micro-thresholds, whitelists, and denylists to control exactly what your agent can spend.
Your agent's spending policy is the primary safety layer between your AI and your on-chain funds. Nebula enforces these rules at the Hub before any transaction reaches Stellar — and optionally re-enforces them in a Soroban smart contract when you enable the on-chain policy contract. You configure every aspect of this policy from the **Policy** section of the [Nebula dashboard](https://nebulaonchain.xyz). Your agent can read the current policy with the `get_policy_status` tool, but it cannot modify policy — all mutations are dashboard-only by design.
## Policy Parameters
These fields control how every spend attempt by your agent is evaluated:
When `true`, all spending is immediately halted regardless of other settings. Use the **Pause** toggle in the Policy dashboard for an instant kill switch if you detect unexpected agent behavior.
A list of Stellar addresses that are always rejected. Any transfer to a denylisted address is blocked before any other check runs. Use this to permanently block known bad actors or addresses your agent should never interact with.
The maximum total USDC your agent can spend in a single calendar day. This cap is cumulative — once your agent's daily spend reaches this number, all further transfers are rejected until the daily counter resets. Set this to a comfortable ceiling that covers normal operations with some headroom.
The maximum USDC allowed in a single transaction. Any transfer above this amount is rejected outright — even if the daily cap has not been reached. This is your most direct control over large individual spends.
Transactions at or below this USDC amount are auto-approved with no human confirmation required (as long as the destination is not denylisted). This is ideal for routine small payments like per-request API fees. Setting this to `0.01` USDC, for example, lets your agent pay tiny micropayments completely hands-free.
A list of trusted Stellar addresses. Transfers to a whitelisted address are auto-approved without requiring human confirmation, provided the amount is within `max_per_call` and the daily cap. Whitelisting does **not** override the per-transaction or daily caps — it only skips the confirmation step.
## How the Decision Flow Works
Every time your agent attempts a transfer, Nebula evaluates it through a fixed sequence of checks. Understanding this order helps you tune your policy correctly:
1. **Paused check** — If `paused` is `true`, the transaction is rejected immediately with `policy_paused`. Nothing else is evaluated.
2. **Denylist check** — If the destination address is on your `denylist`, the transaction is rejected with `destination_denylisted`.
3. **Daily cap check** — If adding this transaction's amount to today's running total would exceed `max_per_day`, the transaction is rejected with `exceeds_daily_cap`.
4. **Per-transaction cap check** — If the transaction amount alone exceeds `max_per_call`, it is rejected with `exceeds_per_tx_cap`.
5. **Micro-threshold check** — If the amount is at or below `micro_threshold`, the transaction is auto-approved. No human confirmation needed.
6. **Whitelist check** — If the destination is on your `whitelist` (and the amount is within caps), the transaction is auto-approved.
7. **New destination confirmation** — If none of the above granted automatic approval, your agent receives a `confirmation_required` response. A human must approve the transaction from the [Approvals tab](https://nebulaonchain.xyz) of the dashboard before it proceeds.
XLM transfers are converted to their USDC equivalent at the live exchange rate before being evaluated against these USDC-denominated caps.
## On-Chain vs Off-Chain Enforcement
By default, policy is enforced off-chain at the Nebula Hub — fast and flexible. When your deployment has `POLICY_CONTRACT_ID` set, Nebula deploys a Soroban smart contract on Stellar that re-enforces the same `max_per_call` and `max_per_day` limits directly on-chain. This means:
* Limits are verifiable by anyone inspecting the Stellar ledger.
* Even if the Hub were bypassed, the contract would reject over-limit transactions.
* Policy updates made in the dashboard are synced to the contract.
On-chain enforcement adds a small amount of latency per transaction (one Soroban invocation) but provides stronger, auditable guarantees. It is recommended for production deployments handling meaningful value.
## Tips for Tuning Your Policy
Set `micro_threshold` to match your smallest expected routine payment — for example `0.01` USDC for per-call API fees. This keeps your agent fluid for small operations without requiring approvals.
Add the addresses of APIs or services your agent uses regularly to your `whitelist`. Your agent can pay them up to `max_per_call` without interrupting the user for confirmation every time.
Use the **Pause** toggle as an emergency stop. If your agent starts behaving unexpectedly, pausing is instant and requires no code changes or redeployment.
Start with conservative caps (`max_per_call: 1`, `max_per_day: 10`) and raise them as you gain confidence in your agent's behavior. It is much easier to loosen limits than to recover from unexpected large transfers.
Your agent reads policy via `get_policy_status` but cannot write it. Never give your agent a dashboard token or any credential that allows policy mutation. Policy changes are dashboard-only by design.