Simulate a rule
Dry-run a rule against sample event data. No ledger changes occur.
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, soparticipant.balance.<symbol>conditions evaluate against actual values. Returns404if the participant doesn’t exist. Still a dry run: nothing is locked or written.participant_state: caller-supplied mock state (tags,counters,attributes, optionallytiersandbalances). Counter values may be JSON numbers or decimal strings; both are evaluated numerically.
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.
| Action type | Result fields |
|---|---|
CREDIT, DEBIT, HOLD, RELEASE, FORFEIT | amount, asset_symbol, description |
COUNTER | current_value, projected_value, value, description |
TAG | current_tags, would_add, description |
UNTAG | current_tags, would_remove, description |
SET_ATTRIBUTE | current_value, would_change, description |
SET_TIER | description |
SCHEDULE_EVENT | payload, description |
BROADCAST | payload, description |
VOID_HOLD actions are not yet supported in simulation. SCHEDULE_EVENT and BROADCAST are not executed, but their payload 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.
Authorizations
API key passed in the X-API-Key header.
Path Parameters
Rule ID
Body
Sample event and optional participant state
Event is the sample event data to evaluate against the rule. Kept as raw JSON so numeric values can be precision-checked before the float64 decode (numbers above ±2^53 are rejected — SCR-323).
{ "amount": 75, "type": "purchase" }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.
"550e8400-e29b-41d4-a716-446655440000"
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.
{
"attributes": { "region": "US" },
"counters": { "purchase_count": 9 },
"tags": ["vip"]
}Response
Simulation result
Evaluation contains the simulation results
Rule contains metadata about the rule that was simulated
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.