Simulation

Matcher exposes two read-only simulation endpoints so you can answer “what would happen?” before you commit configuration. They are match simulation (will this rule match?) and fee simulation (what fees would this schedule charge?). Neither persists anything.

Match simulation

Preview how a single rule would match a context’s unmatched transactions, without committing anything. Choose an existing configured rule (ruleId) or an inline candidate rule (rule).

curl -X POST "https://api.matcher.example.com/v1/matching/simulate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contextId": "550e8400-e29b-41d4-a716-446655440000",
    "rule": {
      "type": "TOLERANCE",
      "config": { "percentTolerance": "0.01" }
    },
    "sampleLimit": 25
  }'

Supply exactly one of:

ruleId: preview an existing configured rule of the context.
rule: preview an un-persisted candidate definition (type is one of EXACT, TOLERANCE, DATE_LAG, FUZZY, plus its config).

Supplying both, or neither, returns 400. sampleLimit (1–200, default 25) caps the returned would-match pairs. The response reports how many 1:1 groups the rule would form and the per-side unmatched counts. It also returns a bounded sample of would-match pairs, each with a confidence score and per-component rationale:

{
  "ruleType": "TOLERANCE",
  "matchedGroups": 12,
  "unmatchedLeft": 3,
  "unmatchedRight": 5,
  "sampleTruncated": false,
  "sample": [
    {
      "left":  { "id": "...", "amount": "100.00", "currency": "BRL", "date": "2025-06-01T00:00:00Z" },
      "right": { "id": "...", "amount": "100.00", "currency": "BRL", "date": "2025-06-01T00:00:00Z" },
      "score": 90,
      "why": { "amountMatch": true, "currencyMatch": true, "dateMatch": true, "referenceScore": 0 },
      "amountDelta": "0.00",
      "dateDeltaDays": 0
    }
  ]
}

Scope: the simulation scores by the deterministic rule engine over the raw transaction amounts. It does not apply run-time fee normalization or the FX-variance band, and it previews only 1:1 pairwise grouping (no 1:N/N:M allocation). The simulation does not count a pair that only matches after fee normalization, inside the FX band, or via allocation.

Fee simulation

Calculate fees for a given gross amount using a specific fee schedule. Use it to validate a schedule’s rules before you attach it to a context.

curl -X POST "https://api.matcher.example.com/v1/fee-schedules/{scheduleId}/simulate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "grossAmount": "100.00", "currency": "USD" }'

The response returns the net amount, the total fee, and a per-item breakdown:

{
  "grossAmount": "100.00",
  "netAmount": "97.70",
  "totalFee": "2.30",
  "currency": "USD",
  "items": [
    { "name": "interchange", "fee": "1.50", "baseUsed": "100.00" }
  ]
}

Fee simulation has no transaction metadata, so expression-fee items that require a transaction identifier surface their missing-identifier error as a 4xx. A missing schedule returns 404.

When to use each

Use	When
Match simulation (`/matching/simulate`)	You are authoring or reviewing a match rule and want to see how many transactions it would group, and which pairs, before committing it.
Fee simulation (`/fee-schedules/{scheduleId}/simulate`)	You are configuring a fee schedule and want to verify the net/fee breakdown it would produce for a representative gross amount.

Both endpoints remain strictly read-only. They never persist a run, group, item, rule, or transaction. The tenant always comes from the JWT.

Response codes

Status	Meaning
`200`	Simulation returned
`400`	Invalid input (ambiguous/missing rule, invalid ids, invalid gross amount)
`404`	Context, rule, or fee schedule not found
`503`	Match simulation not available

Overview

Guides

Matcher UI

MCP Server

Operations

Match simulation

Fee simulation

When to use each

Response codes

​Match simulation

​Fee simulation

​When to use each

​Response codes

Match simulation

Fee simulation

When to use each

Response codes