Skip to main content
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. 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:
​
paused
boolean
default:"false"
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.
​
denylist
string[]
default:"[]"
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.
​
max_per_day
number
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.
​
max_per_call
number
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.
​
micro_threshold
number
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.
​
whitelist
string[]
default:"[]"
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 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.