Agent Spend Policy Specification

Reference implementation

@axiru/agent-spend-guardrails

The reference TypeScript evaluator: defineSpendPolicy and guardAgentSpend implement the full rule set, the precedence ladder, fail-closed error handling, and canonical fingerprints as a pure in-process library. Apache-2.0, zero dependencies, zero network calls.

On npm →

Types and registries

@axiru/spec

The vocabulary as code: OutboundValueTransfer types, policy schema v2, the rail registry, runtime type guards, and the reason-code registry. If you are building an independent implementation, this package is the typed surface of this document.

On npm →

Deployed gate

buzz-axiru

A gating MCP proxy for Block's Buzz agents that runs the reference evaluator in the decision path: payment-class tool calls are allowed, denied, or parked for human approval per this spec, and every decision lands in a hash-chained local log.

On GitHub →

Origin

Axiru hosted engine

The spec is derived from the production decision engine behind Axiru, which evaluates live agent-initiated transfers across card, stablecoin, and pay-per-request rails. The document is the extraction; the engine is where the semantics were earned.

Agent Controls →

In scope

The policy document format (JSON, schema_version: 2). Rule kinds and their matching semantics. Decision outcomes, precedence, and mode resolution (shadow vs enforcing). Canonical reason-code namespaces. Determinism and replay requirements. A conformance checklist.

Out of scope

Transport, storage, key management, transaction signing, and rail-specific execution. This spec governs the decision, not the movement of funds. Protocol and wallet layers authorize keys and transactions; this spec expresses organization-level policy across rails.

4.1 rail

{ "kind": "rail", "in": ["x402", "usdc_solana"] }

Membership on the transfer's rail identifier. An empty in list matches; a rail in the list matches; otherwise no match.

4.2 rail_action

{ "kind": "rail_action", "in": ["refund", "payout"] }

Same membership semantics as rail. Action strings vary by rail; the evaluator MUST NOT enforce cross-rail action-name compatibility. That is the policy author's responsibility.

4.3 amount

{ "kind": "amount", "currency": "USDC", "gte": "50000000", "lte": "1000000000" }

currency denominates gte and lte, which are integer strings compared with arbitrary-precision arithmetic. An optional fx_base converts the transfer amount first via a caller-injected pure FX resolver and MUST equal currency. A currency mismatch with no fx_base is a rule evaluation error (section 6.4), never a silent match or non-match by value.

4.4 initiator_kind

{ "kind": "initiator_kind", "in": ["agent", "automation"] }

Membership on initiator.kind (human, agent, or automation).

4.5 initiator_id

{ "kind": "initiator_id", "in": ["agent_procurement_1"] }

Membership on initiator.id.

4.6 agent_scope

{ "kind": "agent_scope", "has_all": ["payments.create"], "has_none": ["payments.unlimited"] }

Both lists empty or absent: match. Non-agent initiator with a non-empty has_all: no match; non-agent with only has_none set: match. An agent lacking any has_all scope, or holding any has_none scope: no match. An agent record missing scope metadata is a rule evaluation error (fail closed).

4.7 counterparty

{ "kind": "counterparty", "kind_in": ["merchant"], "id_in": ["m_1"], "country_in": ["US"], "country_not_in": ["KP"] }

All sub-fields optional and independently ANDed. country_in with no country on the transfer is a no-match; country_not_in with no country on the transfer matches (absence cannot be in the list). Country codes are uppercase ISO-3166-1 alpha-2.

4.8 rolling_window

{ "kind": "rolling_window", "window": "24h", "aggregate": "sum_amount", "op": "gte", "value": "100000000" }

window is 24h or 30d; aggregate is sum_amount (minor units) or count; op is gte or lte; value is an integer string of arbitrary precision. An optional group_by is a grouping hint: implementations that do not compute per-group aggregates MUST treat a set group_by as a rule evaluation error (fail closed), never as an org-level comparison. The caller-supplied aggregates in policy_inputs describe PRIOR activity and exclude the transfer under evaluation. For sum_amount the comparison is request-inclusive: implementations MUST add the transfer's amount.minor_units to the prior aggregate before applying op, so a single transfer cannot leap over an amount cap that its prior spend alone would not have hit. For count the comparison is against the prior count only (every transfer contributes exactly 1, so no equivalent jump exists). See also the zero-sentinel requirement in 6.5.

4.9 time_of_day

{ "kind": "time_of_day", "tz": "America/New_York", "ranges": [{ "start": 9, "end": 17 }] }

Matches when rail_event_at, projected into the IANA timezone tz, falls in ANY range. Ranges are whole hours, inclusive start, exclusive end. Cross-midnight ranges (start > end) mean [start, 24) union [0, end). An invalid timezone or an empty ranges array is a rule evaluation error. DST MUST be honored via the timezone database.

4.10 custom_expression

{ "kind": "custom_expression", "expression": "!(ovt.counterparty.id in [\"m_1\", \"m_2\"])" }

A sandboxed boolean expression over the transfer record. Conforming evaluators MUST guarantee determinism (no clock, randomness, or I/O; the only inputs are the transfer fields and the injected evaluation clock now, in epoch milliseconds), isolation (no access to host globals, prototypes, or processes), a bounded evaluation budget (exhaustion is a rule evaluation error), and at minimum this grammar: &&, ||, !, comparisons, in [literals], parentheses, string, number, boolean, and null literals, and dotted field paths rooted at ovt. Expressions that do not evaluate to a boolean are rule evaluation errors.

6.2 Precedence

deny  >  require_approval  >  allow

Among matched, enforcing policies, one matched deny wins outright, regardless of how many allow or require_approval policies also matched. Within the same effect tier, implementations MUST apply a deterministic tiebreak; the reference implementation uses policy version descending, then policy id ascending, so replays reproduce the identical winner. If no policy matches, the decision is allow with guardrails.allow.default. (Deployments wanting default-deny express it as an explicit catch-all policy with an empty rule list.)

6.3 Shadow vs enforcing

Enforcing policies are evaluated, affect the outcome, and are recorded in reasons. Shadow policies are evaluated and recorded but MUST NOT change the outcome. Disabled policies are not evaluated at all. When only shadow policies matched, the outcome is allow and the decision MUST carry a distinguishable marker (guardrails.deny.shadow_mode_forced as the summary) so operators can see what enforcement would have done. Every new policy SHOULD begin life in shadow mode; this is the graduated-autonomy on-ramp.

6.4 Fail closed on rule evaluation errors

A rule that cannot be evaluated (unparseable expression, invalid timezone, currency mismatch without FX, budget exhaustion, unknown rule kind from a newer spec revision) makes its policy non-matching AND degrades the decision: a clean allow MUST be demoted to require_approval with a diagnostic reason. An evaluation error MUST NOT silently produce allow. Errors on shadow-mode policies MUST NOT degrade live traffic. At the transfer level, a rail the implementation cannot evaluate MUST produce deny with guardrails.deny.unknown_rail.

6.5 Zero-sentinel velocity escalation

If at least one enforcing policy in scope contains a rolling_window rule and the transfer's policy_inputs are all zero (the sentinel emitted by callers that did not compute aggregates), the evaluator cannot distinguish no prior activity from aggregates missing. A gte-deny rule would be unfireable and an lte-allow rule trivially true, so a clean allow MUST be demoted to require_approval with guardrails.pending.velocity_inputs_unavailable. Existing require_approval and deny outcomes keep their action and gain the diagnostic reason. Known accepted false positive: an org or agent with genuinely zero history receives one conservative approval on its first transfer under a velocity policy.

7.2 Canonical fingerprint

Each transfer record MUST carry a fingerprint of the form sha256: followed by 64 lowercase hex characters, computed over a canonical JSON serialization of at least (rail, rail_action, amount, initiator, counterparty, context). Canonical means object keys sorted lexicographically at every nesting level, amounts serialized as base-10 integer strings (floats, NaN, and Infinity rejected), and no insignificant whitespace. Two structurally identical transfers MUST produce identical fingerprints regardless of construction order. The fingerprint is the replay and idempotency key.

7.3 Replay

Given the persisted transfer record, the policy documents at their evaluated versions, and the evaluation clock, re-running evaluation MUST reproduce the original decision bit for bit: same outcome, same reason codes in the same order, same decision id. This is why policy version is monotonic and persisted per decision, and why timestamps and aggregates travel with the transfer record rather than being re-derived at replay time.

Document format

• Accepts policy documents with schema_version: 2 and all fields in section 3.
• Rejects user policies whose effect.reason_code uses guardrails.* or a vendor-reserved prefix.

Rules

• Implements all ten rule kinds of section 4 with the stated match semantics, or treats unimplemented kinds as rule evaluation errors (never as matches or silent skips).
• Empty membership lists match; empty time_of_day.ranges errors.
• Amount and rolling-window comparisons use arbitrary-precision integers; no floating point in any monetary path.
• custom_expression evaluation is sandboxed, budgeted, and deterministic per 4.10.

Evaluation

• AND within a policy, OR across policies (6.1).
• Precedence deny > require_approval > allow with a deterministic tiebreak (6.2).
• Shadow policies recorded but never enforced; shadow-only matches carry the marker summary (6.3).
• Rule evaluation errors demote clean allows to require_approval and never silently allow (6.4).
• Unknown rails produce deny with guardrails.deny.unknown_rail (6.4).
• Zero-sentinel aggregates with enforcing velocity policies demote clean allows to require_approval (6.5).
• Decisions carry a non-empty ordered reason list, winner first (5.2, 6.6).

Determinism

• Evaluation is pure: no I/O, no ambient clock, no randomness (7.1).
• Canonical sha256: fingerprints per 7.2.
• Bit-for-bit replay per 7.3.