> Documentation index for agents: https://docs.rocketride.ai/llms.txt

# currency_convert_explicit

A RocketRide filter node that converts structured monetary facts at a rate and
date you explicitly supply. Pick it when a financial pipeline needs a
reproducible, auditable conversion step rather than a live exchange-rate lookup
or a node that only labels currencies.

## What it does

The node reads and re-emits the `answers` lane. For a fact whose configured
currency field matches the source currency, it preserves the original fact,
adds a `converted` amount and currency, and appends a provenance entry with the
rate, date, and source/target currencies. It never fetches rates or contacts a
network service, so the result depends only on the stated configuration.

Input may be one JSON fact object or a list of fact objects. Plain text, scalar
JSON, non-fact objects, invalid amounts, and facts in another currency pass
through unchanged, making this a safe opt-in step after structured extraction
or normalization.

## Lanes

| Lane in | Lane out | Description |
| --- | --- | --- |
| `answers` | `answers` | Convert matching JSON fact records and forward every input record once. |

## Configuration

Set the source and target codes, state the conversion rate deliberately, then
align the amount and currency field names with the fact schema produced
upstream. The default profile supplies EUR-to-USD field names and a neutral
rate, but there is only one profile and these individual fields are what tailor
the conversion.

### Source and target currency

**Source currency** selects which facts are eligible; matching is
case-insensitive. **Target currency** is written exactly as configured into the
new `converted.currency` value. Keep both codes non-empty: if either is empty,
the node logs a warning and all answers pass through unchanged. Change the
field names below if an upstream extractor uses names other than `amount` and
`currency`.

### Conversion rate and rate date

**Conversion rate** is the multiplier in `target = source × rate`; it is not
retrieved or inferred. Supply the rate used by the relevant reporting policy
and record its applicable ISO-8601 date in **Rate date** so it is retained in
the provenance entry. A rate that cannot be interpreted as a finite number
causes a warning and leaves all answers unchanged rather than failing the run.

### Amount and currency fields

**Amount field** and **Currency field** name the keys to read from each fact.
The amount may be an integer, float, decimal-compatible string, or `Decimal`;
booleans and non-finite values are not monetary amounts and are left
unchanged. A missing field, non-string currency, or non-matching source
currency also leaves that fact untouched.

### Rounding decimals

**Rounding decimals** controls the fractional digits in `converted.amount` and
defaults to 2. Results use decimal arithmetic and round half-up, which avoids
binary floating-point conversion effects before the final JSON number is
written. Use 0 for whole-unit results or increase it, up to 10 in the
configuration schema, when the downstream fact contract needs more precision.

## Notes

### Output and provenance

The original amount and currency are never modified. The node creates a new
top-level `converted` object and adds a provenance object whose `op` is
`currency_convert_explicit`. An existing provenance list is copied and
appended to; a non-list existing value is preserved as the first item of a new
list. A later conversion therefore replaces the `converted` block but retains
earlier provenance entries.

### Answer forwarding

The node suppresses the engine's default immediate forward, collects converted
payloads for the input object, then writes each one at closing. This prevents
duplicates while preserving the distinction between a JSON answer and plain
text that merely looks like JSON. The node is experimental.

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `currency_convert_explicit.amount_field` | `string` | **Amount field**<br/>The fact field holding the numeric amount to convert. | `"amount"` |
| `currency_convert_explicit.currency_field` | `string` | **Currency field**<br/>The fact field holding the currency code. | `"currency"` |
| `currency_convert_explicit.decimals` | `integer` | **Rounding decimals**<br/>Number of fractional digits for the converted amount (rounded half-up). | `2` |
| `currency_convert_explicit.profile` | `string` | **Conversion**<br/>Explicit currency conversion configuration | `"default"` |
| `currency_convert_explicit.rate` | `number` | **Conversion rate**<br/>The stated multiplier applied to the source amount (target = source × rate). Supply the rate deliberately; nothing is fetched. | `1` |
| `currency_convert_explicit.rate_date` | `string` | **Rate date**<br/>The date the rate applies to (ISO 8601, e.g. 2026-06-30). Recorded in the conversion provenance. | `""` |
| `currency_convert_explicit.source_currency` | `string` | **Source currency**<br/>Currency code to convert FROM (e.g. EUR). Only facts tagged with this currency are converted; case-insensitive. | `"EUR"` |
| `currency_convert_explicit.target_currency` | `string` | **Target currency**<br/>Currency code to convert TO (e.g. USD). | `"USD"` |

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/currency_convert_explicit)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->
