/self/limits

Return effective spend caps, operation permissions, and current-period usage

Requires API-key authentication (agentAuth, agentId).

Purpose: return the agent's effective spend caps, effective operation permissions, and current-period usage.

Auth and scope: header-key auth or OAuth agent:read.

Idempotency: not required.

Request: no body.

Response:

{
  "ok": true,
  "spend_limits": {
    "per_tx_usd": "5",
    "per_period_usd": "100",
    "lifetime_usd": null,
    "max_txs_per_period": null,
    "tx_cooldown_blocks": null,
    "fail_on_zero_price": true
  },
  "swap_limits": {
    "max_slippage_bps": null,
    "max_swaps_per_period": 2
  },
  "permissions": {
    "operation_types": ["payment", "earn.deposit", "earn.withdraw"],
    "cannot": ["debt.borrow", "debt.repay"]
  },
  "current_usage": {
    "txs_in_period": 21,
    "spent_in_period_usd": "13.91",
    "swaps_in_period": 2,
    "total_txs": 62,
    "total_spent_usd": "24.64"
  }
}

Caps are effective: the on-chain wallet enforces both the manager-specific and the wallet-wide global settings, so each field is combined the way the contract checks it — neither is a simple fallback for the other:

• USD caps (per_tx_usd, per_period_usd, lifetime_usd), the transaction-count cap (max_txs_per_period), and max slippage (max_slippage_bps): the tighter (lower) nonzero of the two wins.
• Cooldown (tx_cooldown_blocks): the stricter (larger) nonzero value wins.
• fail_on_zero_price: the boolean OR of the two (either side can reject a zero-priced transaction).
• max_swaps_per_period: the manager value when it sets one, otherwise the wallet-wide global — the one field that is a manager-over-global fallback.
• permissions: the intersection of the manager-specific and wallet-global grants; one_off_payment.create additionally requires the wallet-global cheque settings (canManagersCreateCheques and canManagerPay).

USD caps are decimal strings; a null cap means no limit of that kind is configured at either level. A manager-only or manager-over-global view would misreport the caps and grants the contract combines with the global side. permissions.operation_types lists the operations this agent is actually granted and cannot the rest — unlike GET /v1/agent/self, which returns the global catalog. Unlike the rest of /self, this endpoint performs live on-chain reads.

Use it to size a payment before submitting (rather than discovering a cap via limit_exceeded) and to check whether an operation is permitted before attempting it.

Common errors: authentication_failed, agent_disabled, insufficient_scope. Authentication runs before the route handler, so reads can also return the lifecycle errors agent_not_yet_active and agent_expired for an agent outside its active window.