Skip to main content
POST
Simulate a rule
Dry-runs a rule against sample data. Nothing persists: no balances move, no counters increment, no events are recorded. This endpoint evaluates one rule. It does not execute other rules or rule sets in the program, so it cannot prove cross-set ordering or set-local stop_after_match behavior. See Testing multiple rule sets for the full-program test boundary. The event field is required and should mirror a real event payload. As with real ingestion, numeric values whose magnitude exceeds 2^53 are rejected with 400 amount_precision_exceeded; send very large values as strings. Participant context comes from one of two mutually exclusive sources (supplying both returns a 400):
  • participant_id: loads a real participant’s current state and ledger balances, so participant.balance.<symbol> conditions evaluate against actual values. Returns 404 if the participant doesn’t exist. Still a dry run: nothing is locked or written.
  • participant_state: caller-supplied mock state (tags, counters, attributes, optionally tiers and balances). Counter values may be JSON numbers or decimal strings; both are evaluated numerically.
With neither, the condition evaluates against empty defaults (counters 0, no tags, attributes, tiers, or balances), and the response carries a missing_participant_context warning if the condition reads participant state. Balance comparisons never match without balances. The response pairs the rule’s metadata (rule) with the simulation outcome (evaluation): matched, status (evaluated, or condition_failed with a reason), and per-action results when matched. Result fields vary by action type; state projections (current_value, would_add, and similar) are included only when the action targets the event participant. An action whose target names a recipient also returns resolved_target, which shows who the action would reach: the resolved external_id or participant_id for a dynamic target, participant_id for a static participant id, program_id for the program, or group_id for a group. If the target can’t be resolved, the action’s error field says why. Asset action results show where the value would go. from_bucket is the bucket the action takes value from, and to_bucket is the bucket it adds value to. Both buckets belong to the action’s target, except for VOID_HOLD. A VOID_HOLD returns the value to where it came from, so its to_bucket is AVAILABLE on the program wallet for a PREFUNDED asset, or on system issuance for an UNLIMITED asset. For a partial VOID_HOLD, amount is the rewards the void would cancel, rounded to the asset’s scale. Use it to check the amount before the rule runs. Simulation does not read pending rewards, so amount is not capped at what the participant has pending. Without amount, the result has no amount field because the void cancels all pending rewards for the reference. A CREDIT with a reference_id and no bucket, or "bucket": "AVAILABLE", is a settlement, so its result shows "settles_reference": true. The flag does not mean pending rewards exist for that reference. When the CREDIT runs, it settles the pending rewards for the reference. If there are none, it credits the full amount as new rewards. A settlement CREDIT lands in DEFERRED when its matures_at is in the future. expires_at and matures_at are full timestamps, including fractional seconds. A duration such as 30d counts from the time of the request, so a live run of the rule computes a later timestamp. Simulation uses balances from participant_id or participant_state to evaluate the condition and any action expression that reads them. The actions do not run against the ledger or look at lots, so a result does not show whether pending rewards exist or which lots an action would use. A rule configuration simulation shows that in lot_diffs. SCHEDULE_EVENT and BROADCAST are not executed, but their event_data templates are resolved, so a bad template surfaces here before the rule ever fires on a live event. Amount constraints match production: an asset action whose amount resolves to zero, negative, or beyond the precision-safe range fails in its result (COUNTER deltas may still be negative). To check CEL syntax without an existing rule, use the validate endpoint; to dry-run an unsaved rule, use simulate a draft rule.
For usage patterns and examples, see the Writing Rules guide.

Authorizations

​
X-API-Key
string
header
required

API key passed in the X-API-Key header.

Path Parameters

​
id
string<uuid>
required

Rule ID

Body

application/json

Sample event and optional participant state

​
diagnostics
boolean

Diagnostics opts into clause values, missing paths, short-circuit decisions, active-window and reachability outcomes. The normal response remains compact.

Example:

true

​
event
object

Sample event data to evaluate against the rule. Numbers with a magnitude greater than 2^53 are rejected to prevent loss of precision. Supply exactly one of event or event_id.

Example:
​
event_id
string<uuid>

ID of a stored event to test. Uses its original data and timestamp, and the rule version recorded for that event when available.

Example:

"550e8400-e29b-41d4-a716-446655440004"

​
event_timestamp
string<date-time>

When the sample event occurred. Used to check whether it falls within the rule's active window. Cannot be used with event_id, which uses the stored timestamp.

Example:

"2026-07-21T12:00:00Z"

​
participant_id
string<uuid>

ParticipantID optionally identifies a real participant whose current state (tags, counters, attributes, tiers — the same fields production rule evaluation sees) is loaded as the simulation's participant context. Mutually exclusive with participant_state. The simulation remains a dry run: no state is read with locks and nothing is written.

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
participant_state
object

ParticipantState is optional simulated participant state (tags, counters, attributes). Conditions read it via the dot-access shorthand (participant.counter/tag/attribute., with safe defaults) or the get(participant.counters, ...) form, matching production evaluation. Counter values may be JSON numbers or decimal strings (the wire format returned by the participant state endpoints); both are evaluated numerically. Mutually exclusive with participant_id.

Example:

Response

Simulation result

​
evaluation
object

Evaluation contains the simulation results

​
rule
object

Rule contains metadata about the rule that was simulated

​
warnings
object[]

Non-blocking advisories about the simulation context — e.g. missing_participant_context when the rule's condition reads participant state but the request supplied neither participant_id nor participant_state, so the condition evaluated against empty defaults.