bankproductsBlog

Blog · · EN

/.well-known/bankproducts.json

What if every bank published a machine-readable fee list at a known URL?

We spent a weekend parsing 108 pages of Swiss bank PDFs into a structured database. Six banks, 128 products, 349 fees. It works, but it shouldn't be this hard. There's a simpler way — and it already has precedent.

The idea

Every bank places a single JSON file at:

https://www.example-bank.ch/.well-known/bankproducts.json

That's it. One file. One URL. Machine-readable. Discoverable. No API keys, no registration, no scraping, no PDF parsing.

Any AI agent, comparison site, regulator, or journalist can fetch it with a single HTTP request and know exactly what the bank charges for a Privatkonto, a Visa Debit, a SEPA transfer, or a Platinum credit card.

Precedent

This pattern is well-established on the web:

StandardFilePurpose
security.txt/.well-known/security.txtSecurity contact for vulnerability reports (RFC 9116)
OpenID/.well-known/openid-configurationOAuth/OIDC discovery
Apple/.well-known/apple-app-site-associationUniversal links / app association
robots.txt/robots.txtCrawler directives
This proposal/.well-known/bankproducts.jsonBank products and fees

The .well-known URI prefix is defined by RFC 8615. It's the standard place for machine-discoverable metadata about a website.

What the file looks like

A minimal example — one bank, one product, two fees:

{
  "$schema": "https://bankproducts.info/schema/v1.json",
  "version": "1.0",
  "generated_at": "2026-03-31",

  "bank": {
    "id": "zkb",
    "name": "Zürcher Kantonalbank",
    "country": "CH",
    "bank_type": "cantonal_bank",
    "website": "https://www.zkb.ch"
  },

  "source": {
    "title": "Preisübersicht und Konditionen",
    "valid_from": "2026-04-01",
    "language": "de",
    "url": "https://www.zkb.ch/de/private/konten-karten/preise-konditionen"
  },

  "products": [
    {
      "id": "visa_debit",
      "category": "debit_card",
      "name": "ZKB Visa Debit Card",
      "currency": "CHF",
      "fees": [
        { "type": "annual_fee",  "amount": 0,    "currency": "CHF", "frequency": "monthly",
          "note": "Bis 2 Karten kostenlos" },
        { "type": "fx_markup",   "amount": 1.25, "currency": "percent", "frequency": "per_txn",
          "note": "Max CHF 1.50 pro Transaktion" },
        { "type": "atm_abroad",  "amount": 5,    "currency": "CHF", "frequency": "per_txn" }
      ]
    }
  ]
}

The full ZKB example has 20 products and all their fees in a single 13 KB file: bankproducts.info/.well-known/bankproducts.json

Why this matters now

AI agents need structured data

We're in 2026. AI agents can book flights, manage calendars, and file tax returns. But when a user asks “which bank should I use?” the agent has to either hallucinate an answer or say “I don't know.”

The data exists — it's in PDFs on every bank's website. But PDFs are for humans. An AI agent can't reliably parse a 30-page UBS Preisverzeichnis with its 15 footnotes per page, five overlapping product lines, and context-dependent pricing that changes based on your age, assets, and package combination.

A single JSON file solves this instantly.

The current process is absurd

Here's what it took us to build a comparison database of 6 banks:

  1. Download 7 PDFs from 6 bank websites (108 pages total)
  2. Read every page, understanding that each bank structures their pricing differently
  3. Map “Einzelzahlung” (ZKB), “Zahlungsauftrag” (PostFinance), “Vergütungsauftrag” (Raiffeisen), and “Inlandzahlung” (LGT) to the same concept: a domestic payment
  4. Handle context-dependent pricing (UBS Privatkonto has five different prices depending on your package, assets, and document preferences)
  5. Handle member vs. non-member pricing (Raiffeisen)
  6. Handle domestic vs. international client pricing (LGT)
  7. Normalize everything into a consistent schema
  8. Write 6 SQL files, build a database

This took a weekend with AI assistance. A human doing it manually? Weeks. And it needs to be redone every quarter when prices change.

If each bank published a bankproducts.json, the entire process would be a for loop.

Banks benefit too

This isn't just for consumers and comparison sites. Banks themselves would benefit:

  • Competitive intelligence. Product managers currently download competitors' PDFs and build comparison spreadsheets manually. With bankproducts.json, they could automate this.
  • Regulatory compliance. FINMA and the EU's PSD2/PSD3 increasingly require fee transparency. A standardized format makes compliance trivial.
  • Customer acquisition. If an AI agent can read your fees, it can recommend you. Being discoverable by AI is the new SEO.
  • Accuracy. Third-party comparison sites sometimes get your fees wrong. Publishing the canonical source eliminates that problem.

The format in detail

Top-level structure

{
  "$schema": "https://bankproducts.info/schema/v1.json",  // validation
  "version": "1.0",                                    // format version
  "generated_at": "2026-03-31",                        // when this file was generated
  "bank": { ... },                                     // institution identity
  "source": { ... },                                   // which price list this comes from
  "products": [ ... ]                                  // array of products with nested fees
}

Standardized category values

current_account    savings_account    pillar_3a       vested_benefits
debit_card         credit_card        prepaid_card    package
ebanking           mortgage           wealth_management
term_deposit       safe_deposit       fiduciary_deposit

Standardized fee_type values

// Accounts
account_mgmt   account_opening   account_closing   statement   tax_certificate

// Payments
transfer_domestic   transfer_sepa   transfer_intl   ebill   standing_order
transfer_paper   instant_surcharge   express_fee   our_surcharge

// Cards
annual_fee   replacement_card   fx_markup   cash_advance   topup_fee
atm_domestic_own   atm_domestic_other   atm_abroad

// Packages
base_fee   option_paper

The full taxonomy covers 50+ fee types. Banks only include the ones that apply to their products.

Fees are nested inside products

Not in a separate table. Each product carries its own fees. This makes the file self-contained — you don't need to join anything. An AI agent can find a product and immediately see all its costs.

Key design decision: The file is denormalized on purpose. Duplicating the bank name inside each file (rather than referencing a registry) means any single file is fully self-contained. You don't need to fetch anything else to understand it.

How to adopt it

For banks

  1. Generate a JSON file from your existing fee database (you already have this data internally)
  2. Place it at https://yourbank.ch/.well-known/bankproducts.json
  3. Update it whenever your fees change (typically quarterly)
  4. Optionally: validate it against the schema at bankproducts.info/schema/v1.json

That's literally it. No API to build, no integration to maintain, no vendor to contract. One static file.

For AI agent developers

import httpx, json

bank_url = "https://www.zkb.ch/.well-known/bankproducts.json"
data = httpx.get(bank_url).json()

for product in data["products"]:
    for fee in product["fees"]:
        if fee["type"] == "fx_markup":
            print(f"{product['name']}: {fee['amount']}{fee['currency']}")

Or aggregate all Swiss banks:

banks = ["zkb.ch", "postfinance.ch", "ubs.com", "migrosbank.ch"]

for domain in banks:
    url = f"https://www.{domain}/.well-known/bankproducts.json"
    data = httpx.get(url).json()
    # now you have structured fees for every bank

For regulators

Mandate bankproducts.json as part of fee transparency requirements. One standard, machine-readable format, auditable by anyone. Compliance checking becomes a script, not a team.

What we're doing

We're publishing the reference implementation at bankproducts.info/.well-known/bankproducts.json — generated from ZKB's public Preisverzeichnis as a proof of concept.

We'll generate files for all 6 banks in our database and publish them. If a bank wants to take ownership of their own file, even better — that's the whole point.

The JSON schema, documentation, and validator will be published at github.com/gbits-io/bankproducts_info.

The ask

If you work at a Swiss or Liechtenstein bank and think this makes sense:

  1. Generate a bankproducts.json from your internal fee data
  2. Place it at /.well-known/bankproducts.json
  3. Tell us — we'll add you to the registry

If you build AI agents, comparison tools, or financial products:

  1. Start checking /.well-known/bankproducts.json when you encounter a bank domain
  2. Use the data. Give feedback on the schema.

One bank publishing this file would prove the concept. Two would make it a pattern. Ten would make it a standard.


The bankproducts.json specification is published under CC-BY-4.0. The reference implementation is at bankproducts.info/.well-known/bankproducts.json. The source code and schema are on GitHub.