GirovoAPI

The essentials

• Girovo API is off until the user switches it on: Einstellungen › Girovo API › Girovo API zulassen.
• There is no network and no HTTP. On Windows it is a named pipe, on Linux a Unix socket. Only the signed in user can reach it.
• Every app asks first. Girovo shows a dialog with the app's name, its publisher and each permission on its own.
• Girovo reads the publisher from your app's code signature. What the app says about itself does not count for this. Unsigned apps show as "Herausgeber unbekannt" (publisher unknown).
• Your app only proposes transfers. Girovo opens them filled in, the user checks and sends them, then the bank asks for its approval.
• The user can take back any permission in Einstellungen › Girovo API, for each app on its own.

Connecting

Open the pipe or the socket and send JSON-RPC 2.0, one message per line, ending in \n. Answers and events come back the same way.

Address

The first call: girovo.hello

Every connection starts with girovo.hello. Before it, Girovo answers nothing else. You give your app's name, the permissions you need and a short reason for the user.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "girovo.hello",
  "params": {
    "app": "My Household Book",
    "version": "1.0",
    "permissions": [
      "accounts.read",
      "transactions.read"
    ],
    "reason": "Shows your balances in the household book."
  }
}

The answer comes once the user has decided. granted lists every permission your app has now. The user can switch single permissions off, so check granted.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "granted": [
      "accounts.read",
      "transactions.read"
    ],
    "girovo": {
      "version": "7.0.0",
      "api": 1
    }
  }
}

Wrapped here for reading. On the wire every message is a single line.

What the dialog shows

• Your app's icon and name, from its executable, not from hello.
• "Herausgeber: <name>" with a check mark when Windows trusts the signature. Otherwise "Herausgeber: unbekannt" as a warning, with the file's path.
• Each permission as its own switch. The user can turn single ones off.
• Your reason from hello, marked as the app's words.
• Zulassen (allow) and Ablehnen (refuse).

What can happen

Permissions

Ask only for what your app really needs. If a permission is missing later, you get not_permitted with data.permission. A new hello with that permission opens the dialog just for it.

Methods

All methods start with girovo. Amounts are whole cents with a currency, such as {"cents":1299,"currency":"EUR"}. Days are yyyy-mm-dd, months yyyy-mm. Accounts, bookings and contracts have their own IDs from the read methods.

Errors

An error is a JSON-RPC error. error.data.reason is the code from this list, and error.data.detail the finer reason where there is one, such as never for a setting no app may change. Fields such as permission, param or text come along. The message is meant for your log, not for your interface.

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32003,
    "message": "This app does not have the permission for this method.",
    "data": {
      "reason": "not_permitted",
      "permission": "insights.read"
    }
  }
}

Events

With girovo.events.subscribe your connection listens for events. They come as JSON-RPC notifications without an id, with the method girovo.<kind>. Each kind needs a permission. If the user takes it back, its events stop at once. A subscription holds only for this connection.

→ {"jsonrpc":"2.0","id":3,"method":"girovo.events.subscribe","params":{"kinds":["bookings.new","balances.changed"]}}
← {"jsonrpc":"2.0","id":3,"result":{"subscribed":["bookings.new","balances.changed"]}}
← {"jsonrpc":"2.0","method":"girovo.balances.changed","params":{"account":"a_…","balance":{…},"available":{…}}}

bookings.newPermission: transactions.read

{ account, count, bookings[] }

New bookings on an account that was already loaded.

balances.changedPermission: accounts.read

{ account, balance, available }

A balance changed.

transfer.updatedPermission: transfers.request

{ request, state, text?, changed? }

A transfer request from your app is settled.

Example in Node.js

Connect, hello, read the accounts. No package needed, Node 18 or newer will do. Girovo must be running with Girovo API switched on.

// girovo-client.mjs: node girovo-client.mjs
import net from 'node:net'
import { execFileSync } from 'node:child_process'

function address() {
  if (process.platform === 'win32') {
    // "PC\\name","S-1-5-21-…"
    const line = execFileSync('whoami', ['/user', '/fo', 'csv', '/nh'], { encoding: 'utf8' })
    const sid = line.trim().split(',').pop().replaceAll('"', '')
    return '\\\\.\\pipe\\girovo-api-' + sid
  }
  return process.env.XDG_RUNTIME_DIR + '/girovo-api.sock'
}

const socket = net.connect(address())
socket.setEncoding('utf8')
const waiting = new Map()
let nextId = 1
let buffer = ''

function call(method, params = {}) {
  const id = nextId++
  socket.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n')
  return new Promise((resolve, reject) => waiting.set(id, { resolve, reject }))
}

socket.on('data', (chunk) => {
  buffer += chunk
  let at
  while ((at = buffer.indexOf('\n')) >= 0) {
    const line = buffer.slice(0, at)
    buffer = buffer.slice(at + 1)
    if (!line.trim()) continue
    const message = JSON.parse(line)
    if (!('id' in message)) continue // an event
    const { resolve, reject } = waiting.get(message.id)
    waiting.delete(message.id)
    if (message.error) reject(message.error)
    else resolve(message.result)
  }
})

socket.on('connect', async () => {
  try {
    const hello = await call('girovo.hello', {
      app: 'My Household Book',
      version: '1.0',
      permissions: ['accounts.read'],
      reason: 'Shows your balances in the household book.',
    })
    console.log('Allowed:', hello.granted)
    const { accounts } = await call('girovo.accounts.list')
    for (const a of accounts) console.log(a.name, a.balance?.cents, a.balance?.currency)
  } catch (error) {
    console.error(error.data?.reason, error.message)
  } finally {
    socket.end()
  }
})

Girovo MCP

Girovo MCP connects AI assistants such as Claude Desktop or Codex to Girovo. It is an MCP server over stdio that uses Girovo API. The assistant gets the same dialogs and permissions as any other app.

Where it is

Claude Desktop

Add Girovo MCP to claude_desktop_config.json. On Windows the file is in %APPDATA%\Claude. Write out the full path and double every backslash in JSON.

{
  "mcpServers": {
    "girovo": {
      "command": "C:\\Users\\DEIN-NAME\\AppData\\Local\\Programs\\Girovo\\girovo-mcp.exe"
    }
  }
}

On Linux, command is the full path, for example "/usr/bin/girovo-mcp". Restart the assistant afterwards.

Other MCP clients

The same goes for Codex and other clients: the command is the path to girovo-mcp, with no arguments.

How it behaves

• With the first tool, Girovo MCP asks for accounts.read, transactions.read and insights.read, plus that tool's permission. So one dialog covers the start.
• If a later tool needs another permission, Girovo opens the dialog just for that one.
• On Windows the dialog shows the assistant, for example "Claude (Anthropic PBC) über Girovo MCP". On Linux it shows Girovo MCP with its path.
• If Girovo is closed or Girovo API is off, the tool says so. The next call connects again.

The 19 tools

If your assistant runs in the cloud, everything it reads from Girovo goes to its provider.

Limits

What Girovo allows

What no app can do

• The PIN, Windows Hello and security keys
• "Weitere Banken mit anmelden" and forgetting the device
• Deleting or resetting saved data, restoring a backup
• Girovo API itself: the switch and the permissions, its own included
• The update channel and updates
• Usage data, "Neue Umsätze melden" and the sync
• Sending a transfer: the user always does that in Girovo

Girovo is source available under the PolyForm Perimeter License 1.0.1. You can find the source code on GitHub.