# BPstat Interest Rate Exposure Monitor (`zinin/bpstat-interest-rate-exposure-monitor`) Actor

Unofficial, independent Actor; not affiliated with or endorsed by any named source publisher. Translate official Banco de Portugal rate changes into customer exposure actions.

- **URL**: https://apify.com/zinin/bpstat-interest-rate-exposure-monitor.md
- **Developed by:** [Tim Zinin](https://apify.com/zinin) (community)
- **Categories:** Automation, Other
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $17.00 / 1,000 bpstat interest rate exposure monitors

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## BPstat Interest Rate Exposure Monitor

Translate official Banco de Portugal rate changes into customer exposure actions.

![BPstat Interest Rate Exposure Monitor buyer-input to evidence-to-decision diagram](https://raw.githubusercontent.com/TimmyZinin/apify-actor-assets/39b3eebd2b836f8315464db721642e3ee5847cbe/country20/bpstat-interest-rate-exposure-monitor/readme-hero.webp)

### What you get

BPstat Interest Rate Exposure Monitor turns **Official BPstat series 12533712, Reference date and percentage value, Dataset and series identity** into a bounded **interest-rate exposure report**. The useful product is not a country-labelled scrape. It is an evidence-to-action unit that can be scheduled, called from an API, or placed inside a monitored operations chain.

A successful row gives you Interest exposure report, Rate and cost delta, Reprice, review or monitor. Its stable identity is based on **dataset + series + reference\_date + customer criteria digest**. Customer enrichment is limited to **customer principal, repricing share, and remaining term**. That separation matters: the source supplies observed facts; the buyer supplies criteria; the Actor supplies a reproducible rule application.

#### Product contract

- **Country/source context:** Portugal; json-stat.
- **Buyer:** Portuguese finance, treasury and pricing operations teams.
- **Primary decision noun:** interest-rate exposure report.
- **Billable event:** `exposure-report`.
- **Price per verified event:** $0.02.
- **Stable identity:** dataset + series + reference\_date + customer criteria digest.
- **Accepted private run:** `lgmffvzg5GeoQu3RT` on build `1mcPvhJNvFiBKAhTM`; Dataset rows 1; measured platform usage $0.000403.
- **Boundary:** Use the scenario for operational planning, not as financial advice or a lending quotation.

#### The evidence chain

1. Validate the fixed official/public source route and response semantics.
2. Extract the named business identifiers and domain facts rather than arbitrary links or array positions.
3. Normalize buyer inputs: Principal and repricing share, Remaining term, Stable monitor identity.
4. Apply Establish free baseline, Detect comparable rate change, Calculate exposure delta.
5. Deliver Interest exposure report, Rate and cost delta, Reprice, review or monitor with source receipt and disclaimer.
6. Link the Dataset delivery to the named PPE event and reconcile the run in OUTPUT.

The Actor does not convert an HTTP 200 response into a billable row by default. Source-specific type, marker, identity, row-count, unit, chronology, and completeness checks run before a decision can be delivered.

### Who uses it

The primary users are **Portuguese finance, treasury and pricing operations teams**. They usually have a concrete operational question: which item needs review, where an observed benchmark differs from policy, whether an official change deserves routing, or how to prioritize a bounded set without losing the supporting evidence.

#### Good fit

Use this Actor when the question can be expressed using Principal and repricing share, Remaining term, Stable monitor identity and the intended downstream states align with Interest exposure report, Rate and cost delta, Reprice, review or monitor. A good workflow can name its human owner, evidence-retention rule, acceptable source period, and response to monitor/review/action outcomes.

#### Not a good fit

Do not use it as a general-purpose crawler, unrestricted lead database, professional opinion, safety guarantee, credit or eligibility decision, valuation, or proof of customer intent. Do not expand the fixed source boundary with arbitrary URLs, authenticated pages, personal accounts, or silent residential-proxy fallback.

### How to run

The workflow below belongs to execution: it maps the validated evidence chain into a run, reconciliation, and downstream automation.

![BPstat Interest Rate Exposure Monitor automation and operational workflow diagram](https://raw.githubusercontent.com/TimmyZinin/apify-actor-assets/39b3eebd2b836f8315464db721642e3ee5847cbe/country20/bpstat-interest-rate-exposure-monitor/readme-workflow.webp)

#### Apify Console

1. Open the Actor Input tab.
2. Start from the bounded public example.
3. Replace the durable `requestId` or `monitorId` only when you are creating a genuinely new operation. Keep it unchanged for safe retries.
4. Review source-specific criteria, thresholds, and maximum total charge.
5. Run the Actor.
6. Read both Dataset and KVS `OUTPUT`. Dataset contains item evidence; OUTPUT contains delivery, payment, withholding, and replay truth.

#### Exact accepted private-canary input

The following input was read back from Apify KVS INPUT for accepted run `lgmffvzg5GeoQu3RT`. Its canonical SHA-256 is `9ed7e227f665161e0d00483a42a63df4bd279e4dcc401743e756f5c8da42e44e`. IDs are synthetic campaign identities, not secrets.

```json
{
  "monitorId": "c20_bpstat_interest_rate_exposure_monitor_a99a54df7e30",
  "principalEur": 1000000,
  "repricingSharePct": 75,
  "remainingYears": 2,
  "comparisonMonths": 12,
  "reviewThresholdBps": 10,
  "actionThresholdBps": 25,
  "maxTotalChargeUsd": 1
}
```

#### API start

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/9tJgubhGjT8VwpU9G/runs?token=$APIFY_TOKEN&waitForFinish=60" \
  -H 'content-type: application/json' \
  --data @input.json
```

A successful POST only proves that a run was created. Always follow the returned run ID, wait for a terminal state, then read Dataset and OUTPUT. Do not resend an ambiguous POST with a new identity.

#### Scheduling

Schedule according to the upstream publication cadence, not an arbitrary high-frequency polling loop. Retain the same monitor identity for change products. For one-shot decision products, use a new request identity only for a new buyer decision, criteria set, or source observation that should be independently billed.

### Pricing

This Actor uses Pay Per Event. The named result event is **`exposure-report`**, priced at **$0.02 per verified interest-rate exposure report**. Apify also applies its standard Actor start event according to the published pricing record and memory rules.

#### What is paid

A result event is charged only when the corresponding verified Dataset row or batch is delivered through linked PPE delivery. The runtime checks the live pricing contract before work, compares both the Apify platform cap and customer input cap, and refuses a result it cannot afford.

#### What is free at result level

- `baseline`
- `error`
- `partial`
- `duplicate`
- `withheld`

Baselines for stateful monitors are free. A duplicate committed request is free. A pending/uncertain claim is withheld rather than re-delivered. Source validation failures, zero qualifying decisions, and budget stops do not masquerade as paid successes.

#### Accepted economics evidence

Accepted run `lgmffvzg5GeoQu3RT` reports usage $0.000402655 and event counts:

```json
{
  "apify-actor-start": 1,
  "exposure-report": 1
}
```

This is evidence for that bounded canary, not a promise of future cost, speed, volume, margin, or savings. Source size, platform pricing, memory, and result count can change. Use `maxTotalChargeUsd` and monitor your own runs.

### Input contract

The Input schema rejects unknown fields. Every required field, enum, pattern, minimum, maximum, array bound, and description is part of the public contract. Do not rely on undocumented coercion.

| Field | Type | Required | Default | Bounds | Meaning |
| --- | --- | --- | --- | --- | --- |
| monitorId | string | yes | none | pattern ^\[A-Za-z0-9\_-]{8,64}$ | Stable private automation identifier; do not put personal data in it. |
| principalEur | number | yes | 1000000 | min 0.01; max 1000000000000 | Customer-owned debt principal used only for this exposure scenario. |
| repricingSharePct | number | yes | 100 | min 0.000001; max 100 | Principal share exposed to the benchmark move. |
| remainingYears | number | yes | 1 | min 0.000001; max 50 | Used for a simple non-amortising scenario, not a lending calculation. |
| comparisonMonths | integer | yes | 12 | min 1; max 12 | Use exactly 1 for month-on-month or 12 for year-on-year; runtime rejects intermediate values. |
| reviewThresholdBps | number | no | 10 | min 0 | Absolute benchmark move that changes the action from monitor to review. |
| actionThresholdBps | number | no | 25 | min 0.000001 | Must exceed the review threshold. |
| maxTotalChargeUsd | number | yes | 1 | min 0.005; max 100 | Maximum total run charge accepted by this Actor in addition to the platform cap. |

#### Input design rules

- IDs are idempotency controls, not labels to randomize on every retry.
- Thresholds must express an operational policy that a reviewer understands.
- Customer facts remain customer facts; the Actor does not pretend the source verified them.
- Lists are bounded to protect source terms, runtime, Dataset size, and customer spend.
- `maxTotalChargeUsd` is a customer-side ceiling; the platform run option is authoritative when stricter.
- Secrets do not belong in source URLs, criteria text, Dataset fields, or README examples.

#### Validation before automation

Run one bounded Console example, inspect every Dataset field and OUTPUT, then create the schedule or webhook. If the decision would cause a consequential action, require human approval after the Actor and before the action.

### Real happy, partial, and failure output

#### Accepted Dataset example

The following is an exact Dataset example captured from accepted run `lgmffvzg5GeoQu3RT`; Dataset SHA-256 is `f4b55ece48df710561db62dbc82ec2208092d5e8cb833e3e0ddc711d82cb24f0`.

```json
[
  {
    "schemaVersion": "1.0",
    "product": "bpstat-interest-rate-exposure-monitor",
    "country": "PT",
    "stableId": "BPSTAT:12533712:2026-06-30:c8b8b1a6b934a0f8",
    "decision": "interest-rate exposure report",
    "seriesId": 12533712,
    "latestPeriod": "2026-06-30",
    "source": {
      "datasetId": "6eaa8db94523f54733dddc22479c11a4",
      "seriesId": 12533712,
      "url": "https://bpstat.bportugal.pt/data/v1/domains/21/datasets/6eaa8db94523f54733dddc22479c11a4/?lang=EN&series_ids=12533712&obs_last_n=13&page_size=1",
      "sha256": "228a92117162b63f9b7c8bf728438233b68f7475d35534eec25b83971e95bcbb",
      "bytes": 3054,
      "retrievedAt": "2026-08-14T12:51:43.853Z",
      "sourceUpdatedAt": "2026-07-31T09:30:00Z"
    },
    "attribution": "Source: Banco de Portugal BPstat Data API",
    "action": "review",
    "direction": "higher_cost_pressure",
    "benchmarkRatePct": 4.06,
    "comparisonPeriod": "2025-06-30",
    "comparisonRatePct": 3.86,
    "comparisonMonths": 12,
    "changeBps": 20,
    "thresholds": {
      "reviewBps": 10,
      "actionBps": 25
    },
    "exposure": {
      "principalEur": 1000000,
      "repricingSharePct": 75,
      "repricingPrincipalEur": 750000,
      "remainingYears": 2,
      "estimatedAnnualInterestDeltaEur": 1500,
      "estimatedRemainingSimpleDeltaEur": 3000
    },
    "disclaimer": "Operational scenario based on a public benchmark; not lending, investment, refinancing, or personalised financial advice.",
    "baseline": false,
    "billable": true
  }
]
```

#### Accepted terminal OUTPUT

This exact KVS OUTPUT was captured from the same accepted run; OUTPUT SHA-256 is `6e72f7b40dfb1bf35baa98d15624c5d747fe69bf76da67e162afb27c9cec9029`.

```json
{
  "schemaVersion": "1.0",
  "status": "ok",
  "product": "bpstat-interest-rate-exposure-monitor",
  "delivered": 1,
  "paid": 1,
  "withheld": 0,
  "replaySafe": false,
  "publicationAuthorized": false,
  "finishedAt": "2026-08-14T12:51:44.463Z"
}
```

#### Partial contract shape

The runtime uses a free partial/withheld state when source completeness or delivery certainty is insufficient. This is a contract illustration, not claimed as an additional accepted run:

```json
{
  "schemaVersion": "1.0",
  "status": "partial",
  "product": "bpstat-interest-rate-exposure-monitor",
  "delivered": 0,
  "paid": 0,
  "withheld": 1,
  "replaySafe": false,
  "publicationAuthorized": false,
  "error": "source-specific validation stopped before verified delivery"
}
```

#### Failure contract shape

A bounded source or input failure is free at result level and never claims replay safety unless the runtime can prove it. This is a contract illustration:

```json
{
  "schemaVersion": "1.0",
  "status": "failed",
  "product": "bpstat-interest-rate-exposure-monitor",
  "delivered": 0,
  "paid": 0,
  "withheld": 0,
  "replaySafe": false,
  "publicationAuthorized": false,
  "error": "bounded source or input contract failure"
}
```

#### Reading terminal truth

- `delivered` must reconcile to Dataset rows.
- `paid` must reconcile to billable rows and the named event count.
- `withheld` signals that a row or operation was intentionally not repeated or delivered.
- `replaySafe` is true only for states the runtime can safely replay.
- `publicationAuthorized` is a release boundary, not a customer decision field.

### Field dictionary

#### Dataset

| Dataset field | Type | Operational meaning |
| --- | --- | --- |
| schemaVersion | string | Verified schemaVersion field in the accepted interest-rate exposure report row. |
| product | string | Verified product field in the accepted interest-rate exposure report row. |
| country | string | Verified country field in the accepted interest-rate exposure report row. |
| stableId | string | Verified stableId field in the accepted interest-rate exposure report row. |
| decision | string | Verified decision field in the accepted interest-rate exposure report row. |
| action | string | Verified action field in the accepted interest-rate exposure report row. |
| direction | string | Verified direction field in the accepted interest-rate exposure report row. |
| seriesId | integer | Verified seriesId field in the accepted interest-rate exposure report row. |
| latestPeriod | string | Verified latestPeriod field in the accepted interest-rate exposure report row. |
| benchmarkRatePct | number | Verified benchmarkRatePct field in the accepted interest-rate exposure report row. |
| comparisonPeriod | string | Verified comparisonPeriod field in the accepted interest-rate exposure report row. |
| comparisonRatePct | number | Verified comparisonRatePct field in the accepted interest-rate exposure report row. |
| changeBps | number | Verified changeBps field in the accepted interest-rate exposure report row. |
| exposure | object | Verified exposure field in the accepted interest-rate exposure report row. |
| thresholds | object | Verified thresholds field in the accepted interest-rate exposure report row. |
| source | object | Verified source field in the accepted interest-rate exposure report row. |
| attribution | string | Verified attribution field in the accepted interest-rate exposure report row. |
| disclaimer | string | Verified disclaimer field in the accepted interest-rate exposure report row. |
| baseline | boolean | Verified baseline field in the accepted interest-rate exposure report row. |
| billable | boolean | Verified billable field in the accepted interest-rate exposure report row. |

#### Cross-product evidence fields

- **stableId** — domain identity derived from dataset + series + reference\_date + customer criteria digest; never a source array position.
- **source** — route, official IDs, period, byte/hash receipt, and retrieval time needed to audit the observation.
- **action** — the explicit routing result after applying buyer criteria to validated source facts.
- **criteriaSha256** — integrity fingerprint for normalized criteria; it is not a score.
- **baseline** — true only when a stateful monitor stores its first comparable snapshot for free.
- **billable** — true only when the row is eligible for the named linked delivery event.
- **attribution/disclaimer** — reuse credit and decision boundary that downstream systems should retain.

#### KVS OUTPUT

OUTPUT is the authoritative run-level receipt. It should be stored beside a workflow execution ID. It does not replace Dataset evidence, and Dataset evidence does not replace OUTPUT billing/replay truth. A robust integration rejects mismatched counts rather than guessing.

### Evidence and boundaries

#### Evidence preserved

The adapter retains the official identity and observed facts required for interest-rate exposure report. It also retains source URL/route, source period or publication identity, retrieval timestamp, response or release hash, normalized criteria fingerprint, and the exact action reason exposed by the domain adapter.

#### Semantic source validation

The source contract is **json-stat** on route **direct**. Validation is domain-specific: expected content type, fixed host/path or official catalog relationship, required identifiers, bounded bytes, structural fields, chronology, duplicate identity, and semantic error bodies are checked before delivery. An upstream login page, generic app shell, consent page, empty report, or malformed file must fail closed.

#### Security boundary

Network destinations are fixed to approved official/public hosts. Redirects are either disabled or independently revalidated. DNS and address checks reject local/private targets. Responses are streamed under declared byte limits. Buyer input cannot turn the Actor into SSRF, an open proxy, an authenticated crawler, or a credential relay.

#### Interpretation boundary

Use the scenario for operational planning, not as financial advice or a lending quotation. The Actor reports observed evidence plus a deterministic rule application. It does not prove causality, future behavior, legal status beyond the cited publication, quality, solvency, safety, intent, or permission to contact.

#### Privacy boundary

Submit only operationally necessary criteria. Do not provide passwords, access tokens, private correspondence, sensitive personal data, or arbitrary URLs. If the official source exposes public entity facts, retain them only for the documented decision and according to your own legal basis and retention policy.

### Decision routing

#### Route states

- **Monitor** — evidence is valid but does not cross a review threshold. Store the receipt and wait for the next comparable observation.
- **Review** — evidence crosses a bounded review rule or needs professional confirmation. Create a queue item with source and factors.
- **Action-oriented state** — the explicit rule crosses the action threshold. Require the owner and safeguards appropriate to the domain.
- **Partial** — source completeness is insufficient. Do not interpret missing rows as negative evidence.
- **Withheld/uncertain** — the runtime will not repeat a potentially delivered item. Reconcile by run ID.
- **Failed** — no decision claim was made. Fix the input/source boundary or wait for the official source; do not randomize the request ID.

#### Routing record

Every downstream task should carry stableId, action, factors, source identity, reference period, criteria fingerprint, run ID, Dataset ID, and a link to OUTPUT. This makes it possible to answer “what did we know, which rule ran, and what happened to delivery?” without reconstructing the workflow from logs.

#### Human review

Human review is not a vague disclaimer. Define the reviewer role, response time, evidence they must inspect, allowed dispositions, and whether a changed source observation is required before action. Keep the reviewer decision separate from the Actor row.

### Commercial playbooks

#### 1. Qualification desk

Use Principal and repricing share, Remaining term, Stable monitor identity to decide which records deserve analyst time. Preserve the cited source fields beside the action so a reviewer can reproduce why the row was routed.

#### 2. Scheduled monitor

Run on the cadence of the official source, keep the same durable request or monitor identity where the product supports state, and send only verified changes or decision rows downstream.

#### 3. CRM enrichment

Map Interest exposure report, Rate and cost delta, Reprice, review or monitor into evidence fields instead of overwriting customer master data. Keep the source URL, observation period, stable ID, and disclaimer visible.

#### 4. Operational review queue

Treat “review” as a routing state. Assign an owner, retain the evidence receipt, confirm the current source state, and record the human disposition outside the Actor.

#### 5. Portfolio comparison

Run the same bounded criteria over comparable customer items. Compare factors and source periods, not a bare score detached from its evidence and limitations.

#### 6. Audit export

Export Dataset rows and the KVS OUTPUT receipt together. The Dataset explains each delivered item; OUTPUT explains paid, free, withheld, partial, and replay state for the run.

### Integration recipes

#### JavaScript client

```js
const actorId = '9tJgubhGjT8VwpU9G';
const input = {
  "monitorId": "c20_bpstat_interest_rate_exposure_monitor_a99a54df7e30",
  "principalEur": 1000000,
  "repricingSharePct": 75,
  "remainingYears": 2,
  "comparisonMonths": 12,
  "reviewThresholdBps": 10,
  "actionThresholdBps": 25,
  "maxTotalChargeUsd": 1
};
const start = await fetch(`https://api.apify.com/v2/acts/${actorId}/runs?waitForFinish=60&token=${process.env.APIFY_TOKEN}`, {
  method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(input),
});
const run = (await start.json()).data;
if (!['SUCCEEDED', 'FAILED', 'ABORTED', 'TIMED-OUT'].includes(run.status)) throw new Error('poll run to terminal');
const [rowsResponse, outputResponse] = await Promise.all([
  fetch(`https://api.apify.com/v2/datasets/${run.defaultDatasetId}/items?clean=true&token=${process.env.APIFY_TOKEN}`),
  fetch(`https://api.apify.com/v2/key-value-stores/${run.defaultKeyValueStoreId}/records/OUTPUT?token=${process.env.APIFY_TOKEN}`),
]);
const rows = await rowsResponse.json();
const terminal = await outputResponse.json();
if (terminal.delivered !== rows.length) throw new Error('delivery reconciliation failed');
```

#### Python client

```python
import os, requests
actor_id = '9tJgubhGjT8VwpU9G'
input_payload = {
  "monitorId": "c20_bpstat_interest_rate_exposure_monitor_a99a54df7e30",
  "principalEur": 1000000,
  "repricingSharePct": 75,
  "remainingYears": 2,
  "comparisonMonths": 12,
  "reviewThresholdBps": 10,
  "actionThresholdBps": 25,
  "maxTotalChargeUsd": 1
}
run = requests.post(
    f'https://api.apify.com/v2/acts/{actor_id}/runs',
    params={'token': os.environ['APIFY_TOKEN'], 'waitForFinish': 60},
    json=input_payload, timeout=75,
).json()['data']
rows = requests.get(
    f"https://api.apify.com/v2/datasets/{run['defaultDatasetId']}/items",
    params={'token': os.environ['APIFY_TOKEN'], 'clean': 'true'}, timeout=30,
).json()
output = requests.get(
    f"https://api.apify.com/v2/key-value-stores/{run['defaultKeyValueStoreId']}/records/OUTPUT",
    params={'token': os.environ['APIFY_TOKEN']}, timeout=30,
).json()
assert output['delivered'] == len(rows)
```

#### n8n

1. **Schedule Trigger** or Webhook receives the bounded buyer criteria.
2. **HTTP Request** starts the Actor with an Apify credential stored in n8n credentials, never in the input URL committed to source control.
3. **Wait/Poll** follows the returned run ID to terminal state.
4. Two **HTTP Request** nodes read Dataset and OUTPUT.
5. **Code** checks delivered/paid counts, allowed status, stableId, source period, and action.
6. **Switch** routes monitor, review, action, partial, withheld, and failed states separately.
7. Destination nodes write to Sheets/CRM/ticketing while preserving evidence and disclaimer.

#### Google Sheets

Use one sheet for decision rows keyed by `stableId`, and a second run ledger keyed by `runId`. Recommended decision columns are source period, action, factors, source URL, criteria hash, observation time, and reviewer disposition. Recommended run columns are Dataset ID, delivered, paid, withheld, replaySafe, usage, and OUTPUT link.

#### CRM

Create an evidence/enrichment activity rather than replacing the CRM’s authoritative legal name, valuation, risk status, or account owner. Store the source identity and observation date. Route review/action states into a task with a named owner; leave monitor states as timeline evidence unless policy says otherwise.

#### Webhooks

Use an Apify run-succeeded webhook only as a wake-up signal. Fetch the terminal run, Dataset, and OUTPUT using their IDs, then reconcile. Do not trust arbitrary webhook body fields as the complete decision record, and make the receiver idempotent by run ID plus stableId.

### Operating guide

#### Before launch

- Confirm the official source route and reuse boundary remain current.
- Validate public Input schema descriptions and bounded defaults in the rendered Console.
- Run the small example and retain INPUT, Dataset, OUTPUT, build ID, pricing events, and usage.
- Confirm the source observation period is appropriate for the buyer decision.
- Define downstream owners and allowed dispositions.
- Set a customer cap and monitor actual spend.

#### Daily or scheduled operation

Check terminal status, Dataset count, OUTPUT reconciliation, source period, source hash change, partial flags, and review backlog. When the source has not published a new comparable period, do not fabricate change by rotating an identity. When a source revision changes a prior period, keep both the revision evidence and customer decision history.

#### Incident runbook

1. Stop automatic consequential actions while preserving monitor collection.
2. Identify the exact run, build, INPUT hash, Dataset hash, OUTPUT hash, and source receipt.
3. Determine whether the fault is input validation, source availability, semantic source drift, budget, linked delivery, or downstream mapping.
4. For an ambiguous POST or pending delivery, reconcile the existing run; never start a replacement with a new identity merely to obtain a clean status.
5. For source schema drift, update source-specific fixtures and validators, build a new immutable candidate, and rerun acceptance.
6. Restore automation only after a bounded canary and replay test prove the corrected path.

#### Change management

Treat input/output schemas, identity basis, decision rules, source URLs, legal boundary, and pricing noun as product contracts. Version changes deliberately. A README-only edit must not silently redefine runtime behavior, and a runtime change must update examples and field dictionary before release.

#### Quality checklist

For this product the release gate verifies: Principal and repricing share, Remaining term, Stable monitor identity; Official BPstat series 12533712, Reference date and percentage value, Dataset and series identity; Establish free baseline, Detect comparable rate change, Calculate exposure delta; and Interest exposure report, Rate and cost delta, Reprice, review or monitor. It also checks private candidate provenance, exact build source, PPE configuration, bounded accepted run, free error/duplicate behavior, replay and concurrency safety, two immutable diagrams, README length/sections, rendered Store/Input pages, and all-20 wave balance.

### FAQ

#### Is this a generic country scraper?

No. It is the BPstat Interest Rate Exposure Monitor, designed around interest-rate exposure report and the named official/public source contract. Geography explains the source, not the product category.

#### Does it crawl accounts or private pages?

No. The implementation is pinned to the source routes documented below. It does not log in, bypass an account, collect messages, or broaden itself to arbitrary customer URLs.

#### Can a customer supply an arbitrary URL?

No. Source hosts and paths are fixed or derived only through bounded official catalog routes. Buyer inputs select criteria and customer facts; they do not turn the Actor into an open proxy.

#### What is the primary billable unit?

The single pricing noun is **interest-rate exposure report**, charged through the named event `exposure-report` only when a verified billable Dataset item is linked to delivery.

#### Are errors charged as result events?

No. The contract identifies baseline, error, partial, duplicate, withheld as free result states. Apify platform start charges are separate and visible in the run pricing record.

#### What makes an ID stable?

The identity basis is: dataset + series + reference\_date + customer criteria digest. Mutable ranking, source position, or array offset is not treated as the business identity.

#### Is the score a random hash?

No. The production adapter parses named source fields and applies the explicit rules described in the output. Hashes are used for integrity, criteria fingerprints, and idempotency—not as business scores.

#### Can I treat an action as a professional conclusion?

No. Use the scenario for operational planning, not as financial advice or a lending quotation.

#### How fresh is the data?

Freshness follows the official source and the observation/reference period in the Dataset row. The Actor does not invent a real-time claim when the upstream source is monthly, daily, or a published report.

#### Why preserve a source hash?

It proves which response or release was used and helps distinguish a changed upstream publication from a changed customer criterion. It does not replace the official source URL.

#### What happens on an upstream HTML challenge or error page?

Semantic validators reject the body before decision delivery. A 2xx status alone is not enough; required columns, identifiers, counts, content type, and source-specific markers must pass.

#### Does this require a local proxy?

The accepted product route is the route in the contract: **direct**. A proxy is never a silent fallback and cannot change a legal or reuse boundary.

#### How do retries work?

Reuse the same durable request/monitor identity. A committed request returns a free duplicate state; an uncertain pending delivery is withheld rather than repeated blindly. Inspect OUTPUT before authorizing any new request ID.

#### Can two concurrent runs double-deliver?

The runtime claims a tenant-scoped durable operation before linked delivery. A competing claim is returned as duplicate or withheld. The release gate separately stress-tests this behavior before publication.

#### Where is the authoritative run summary?

KVS record OUTPUT. Dataset rows carry item evidence; OUTPUT carries run-wide counts and replay safety. Store both when the workflow needs auditability.

#### Can I remove the disclaimer downstream?

Do not. Preserve attribution, the product disclaimer, source URL, reference period, and the human-review boundary in any CRM, report, or webhook payload.

#### Does the Actor predict the future?

No. It converts observed official/public evidence and customer criteria into an operational benchmark, monitor, or routing decision. It is not marketed as a forecast unless the product contract explicitly says so—which this one does not.

#### Does it contain personal data?

The product scope is limited to the documented public/aggregate fields and buyer-supplied operational criteria. Do not submit secrets or unnecessary personal data. Review Dataset examples before connecting another system.

#### How should I choose thresholds?

Start with the bounded public example, compare decisions against your own review policy, and change one rule at a time. The Actor exposes Interest exposure report, Rate and cost delta, Reprice, review or monitor so threshold effects remain visible.

#### Why is publicationAuthorized false in canary OUTPUT?

Private acceptance runs deliberately hard-code the publication boundary. Public release is a separate all-20 transaction after source, billing, replay, visual, Store, and anonymous-page gates pass.

#### What sources are contacted?

`https://bpstat.bportugal.pt/data/v1/domains/21/datasets/6eaa8db94523f54733dddc22479c11a4/?lang=EN&series_ids=12533712&obs_last_n=13&page_size=1`

#### Can n8n or Make call it?

Yes. Start a run through the Apify API, wait for terminal status, read Dataset items and OUTPUT, then branch on explicit action/status fields. Never branch only on HTTP 201 from the run-start request.

#### Can I write results to Google Sheets?

Yes. Use stableId as the row key, source reference period as the observation column, and action as a review-routing column. Keep OUTPUT in a separate run ledger sheet.

#### Can I push into a CRM automatically?

Yes, but write evidence into a dedicated enrichment object or timeline entry. Do not silently overwrite authoritative customer fields, and require human review for consequential actions.

#### What should support requests include?

Provide the Actor name, run ID, build number, OUTPUT, source receipt/hash, and a redacted input. Never paste the Apify token or another secret.

#### How do I audit a threshold change?

Keep the old and new normalized criteria, their fingerprints, the same comparable source period, and both decision rows. Explain which of Principal and repricing share, Remaining term, Stable monitor identity changed and why the new policy is authorized.

#### Can I compare different source periods?

Yes, when the domain adapter exposes comparable periods and units. Keep revision and seasonality caveats visible. Never compare ranks or scores across changed definitions without documenting the break.

#### What if the official source revises history?

Retain both source hashes and observation timestamps. A revision is new evidence, not proof that the earlier Actor run was defective. Re-run only under an authorized identity/revision policy.

#### What if the source removes a record?

A stateful product reports removal only when the source contract and completeness checks can distinguish a real removal from a partial response. Otherwise the run is partial or withheld.

#### Should I schedule it every minute?

Usually no. Match the upstream publication cadence and buyer response time. Excess polling adds cost and load without creating fresher official evidence.

### Sources and rights

#### Exact source routes

- https://bpstat.bportugal.pt/data/v1/domains/21/datasets/6eaa8db94523f54733dddc22479c11a4/?lang=EN\&series\_ids=12533712\&obs\_last\_n=13\&page\_size=1

The implementation uses only the route family defined in `contract.json`: kind `json-stat`, host `bpstat.bportugal.pt`, route `direct`. Source metadata, licence/reuse labels, attribution, and product-specific exclusions must be rechecked at production acceptance because public terms and endpoints can change.

#### Reuse and attribution

This is an unofficial Actor, not affiliated with or endorsed by any named source publisher. Preserve emitted attribution and official disclaimers. Do not broaden reuse rights to excluded content, accounts, listings, messages, or customer data.

#### Termos da fonte em português

**Search/source terms:** dados oficiais, prova da fonte, sinal de decisão, monitorizar, rever, agir.

Os registos da fonte são preservados como prova; o resultado não constitui parecer jurídico, financeiro ou garantia de resultado.

The local-language labels help operators find and verify the official source. The binding product contract, input schema, field dictionary, pricing noun, and safety boundary remain the English Store documentation above.

#### Product-specific boundary

- Source evidence: Official BPstat series 12533712; Reference date and percentage value; Dataset and series identity.
- Transformation: Establish free baseline; Detect comparable rate change; Calculate exposure delta.
- Delivered fields: Interest exposure report; Rate and cost delta; Reprice, review or monitor.
- Required interpretation: Use the scenario for operational planning, not as financial advice or a lending quotation.
- Excluded expansion: arbitrary URLs, account access, messages, private datasets, silent proxy fallback, and claims not supported by cited evidence.

#### Support evidence

When reporting a source or decision issue, provide run ID `lgmffvzg5GeoQu3RT`-style identifiers, build number, redacted INPUT, Dataset and OUTPUT hashes, source period and source receipt. Never send an Apify token, password, private correspondence, or unnecessary personal data.

# Actor input Schema

## `monitorId` (type: `string`):

Stable private automation identifier; do not put personal data in it.

## `principalEur` (type: `number`):

Customer-owned debt principal used only for this exposure scenario.

## `repricingSharePct` (type: `number`):

Principal share exposed to the benchmark move.

## `remainingYears` (type: `number`):

Used for a simple non-amortising scenario, not a lending calculation.

## `comparisonMonths` (type: `integer`):

Use exactly 1 for month-on-month or 12 for year-on-year; runtime rejects intermediate values.

## `reviewThresholdBps` (type: `number`):

Absolute benchmark move that changes the action from monitor to review.

## `actionThresholdBps` (type: `number`):

Must exceed the review threshold.

## `maxTotalChargeUsd` (type: `number`):

Maximum total run charge accepted by this Actor in addition to the platform cap.

## Actor input object example

```json
{
  "monitorId": "bpstat_demo_01",
  "principalEur": 1000000,
  "repricingSharePct": 100,
  "remainingYears": 1,
  "comparisonMonths": 12,
  "reviewThresholdBps": 10,
  "actionThresholdBps": 25,
  "maxTotalChargeUsd": 1
}
```

# Actor output Schema

## `results` (type: `string`):

Validated paid decisions and explicit free baseline/error rows.

## `OUTPUT` (type: `string`):

Source hash, delivery, billing and replay-safety counters.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "monitorId": "bpstat_demo_01"
};

// Run the Actor and wait for it to finish
const run = await client.actor("zinin/bpstat-interest-rate-exposure-monitor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "monitorId": "bpstat_demo_01" }

# Run the Actor and wait for it to finish
run = client.actor("zinin/bpstat-interest-rate-exposure-monitor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "monitorId": "bpstat_demo_01"
}' |
apify call zinin/bpstat-interest-rate-exposure-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,zinin/bpstat-interest-rate-exposure-monitor"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/9tJgubhGjT8VwpU9G/builds/4P0CYZbzwtwk6067G/openapi.json