ContractSpec docs

OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

AI index

Powens Open Banking

Powens provides read-only open banking connectivity for ContractSpec applications. The reference integration powers Pocket Family Office by synchronising household bank accounts, transactions, and balances while keeping all raw PII protected.

Setup

Create a Powens BYOK project, then store the credentials in your secret manager. The ContractSpec integration expects the following fields:

{
  "clientId": "powens-client-id",
  "clientSecret": "powens-client-secret",
  "apiKey": "optional-api-key",
  "webhookSecret": "optional-webhook-secret"
}

Configure non-secret settings on the integration connection:

environment: sandbox | production
baseUrl?: https://api-sandbox.powens.com/v2
region?: eu-west-1
pollingIntervalMs?: 300000

See the Powens API documentation for information on generating credentials and managing BYOK projects.

Capabilities

capabilityId: openbanking.accounts.read
provider:
  type: openbanking.powens
  operation: listAccounts

outputs:
  accounts:
    type: BankAccountRecord[]
    description: "Canonical bank account metadata (institution, currency, balances)"

---

capabilityId: openbanking.transactions.read
provider:
  type: openbanking.powens
  operation: listTransactions

inputs:
  accountId:
    type: string
  from?:
    type: string
    description: "ISO timestamp lower bound"
  to?:
    type: string

outputs:
  transactions:
    type: BankTransactionRecord[]
    description: "Canonical transaction ledger entries"

---

capabilityId: openbanking.balances.read
provider:
  type: openbanking.powens
  operation: getBalances

inputs:
  accountId:
    type: string
  balanceTypes?:
    type: string[]

outputs:
  balances:
    type: AccountBalanceRecord[]
    description: "Current/available balances with timestamps"

Primary workflows

Account sync

The workflow pfo.workflow.sync-openbanking-accounts refreshes account metadata, then surfaces canonical records to other automations.

Transaction sync

pfo.workflow.sync-openbanking-transactions ingests incremental transactions for each linked account and stores them in the canonical ledger.

Balance refresh

pfo.workflow.refresh-openbanking-balances retrieves current and available balances to power dashboards and anomaly detection.

Derived financial overview

pfo.workflow.generate-openbanking-overview aggregates balances, category breakdowns, and cashflow trends into the knowledge.financial-overview space. Only derived summaries are exposed to LLMs.

Telemetry & guardrails

  • Telemetry events such as

    openbanking.accounts.synced

    and

    openbanking.transactions.synced

    are emitted automatically with tenant, slot, and config metadata.

  • Guard helpers ensure the

    primaryOpenBanking

    slot is bound and healthy before workflows execute.

  • PII fields (IBAN, counterparty names, descriptions) are redacted via

    redactOpenBankingTelemetryPayload

    before logging or sending telemetry.

Best practices

  • Use BYOK credentials per tenant to avoid cross-tenant exposure.

  • Store only canonical entities (BankAccountRecord, BankTransactionRecord). Never persist raw Powens payloads or customer PII in logs.

  • Run the transaction sync on a schedule appropriate for banking SLAs (e.g. every 15 minutes for cashflow dashboards).

  • Pair ledger updates with derived summaries to feed the knowledge layer instead of exposing raw transactions to agents.

  • Monitor telemetry for

    openbanking.*.sync_failed

    events to detect credential issues early.

Back to Integrations

Next: Stripe