Skip to main content
skill CX Codex

biala-lista — Claude Code skill: company checks and installation

biala-lista is a Claude Code skill that checks Polish companies and VAT status by NIP or REGON. It runs on requests to verify a contractor, bank account, or Polish invoice.

MIT ★ 60 updated 2026-11-15

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add b44x/ai-polish-skills
/plugin install biala-lista@polskie-skille
Open on GitHub

What biala-lista does

The skill queries Poland’s Ministry of Finance registry and returns company and VAT data as JSON. Look up a business by NIP or REGON to retrieve its legal name, address, KRS, and settlement accounts. It can also find a company by bank account, compare an account with a NIP, and validate NIP, REGON, or NRB checksums offline.

The skill runs scripts/biala_lista.py. It requires Python 3.8+ and network access to wl-api.mf.gov.pl; it uses no external libraries and needs no authentication. Add --date=YYYY-MM-DD to check a past date. The API limit is 300 requests per day per IP.

What it helps with

  • check a Polish company’s VAT status by NIP
  • find a business by REGON or bank account
  • match a contractor’s account to its NIP
  • validate a NIP, REGON, or NRB checksum offline

Example prompts for the agent

  • Check the VAT status and settlement accounts for the Polish company with NIP 5260250274.
  • Check whether account PL61109010140000071219812874 is listed for NIP 5260250274.
  • Validate this REGON checksum without querying the API: 123456789.

How to install biala-lista

1Plugin marketplace

/plugin marketplace add b44x/ai-polish-skills
/plugin install biala-lista@polskie-skille

This installs the whole biala-lista plugin with all its skills

2Skills CLI (Vercel)

npx skills add b44x/ai-polish-skills --skill biala-lista -a claude-code

3Manually: put the files in place

~/.claude/skills/biala-lista/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/biala-lista/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about biala-lista

How do I install biala-lista in Claude Code?

Add the marketplace with /plugin marketplace add b44x/ai-polish-skills, then install the skill with /plugin install biala-lista@polskie-skille.

What does biala-lista do?

It retrieves Polish company details and VAT status from the official registry. It can also match a bank account to a company, check an account against a NIP, and validate checksums offline.

What does biala-lista need to run?

It requires Python 3.8+ and network access to wl-api.mf.gov.pl. No external libraries or authentication are required.

Source text

SKILL.md · MIT
---
name: biala-lista
display_name: Biała Lista Podatników VAT
version: 1.0.0
description: >-
  Check Polish businesses and VAT status in the official Ministry of Finance White
  List (Biała Lista Podatników VAT). Verify active VAT payer status (Czynny /
  Zwolniony / Niezarejestrowany), legal company name, REGON, KRS, registered address,
  and settlement bank accounts by NIP or REGON. Check if a contractor's bank account
  is on the whitelist before making B2B transfers (critical for split payment and
  tax deductibility above 15,000 PLN). Reverse-lookup company by 26-digit Polish bank
  account number (NRB/IBAN). Validate NIP, REGON, and IBAN checksums offline. Use
  whenever the user asks about NIP, REGON, Biała Lista VAT, "sprawdź NIP", "sprawdź kontrahenta",
  "status VAT spółki", "czy numer konta jest na białej liście", or verifying a Polish invoice.
category: finance
language: pl
country: PL
license: MIT
author: Michell Hoduń (https://github.com/b44x)
repository: https://github.com/b44x/ai-polish-skills
network: true
authentication: none
source: Ministerstwo Finansów (KAS)
source_type: official_api
official: true
homepage: https://www.podatki.gov.pl/wykaz-podatnikow-vat-wyszukiwarka/
documentation: https://www.gov.pl/web/kas/api-wykazu-podatnikow-vat
rate_limit: 300 requests/day per IP
last_verified: 2026-09-28
tags:
  - biala-lista
  - vat
  - nip
  - regon
  - split-payment
  - podatki
  - faktury
  - rachunek-bankowy
compatibility: Python 3.8+ (standard library only); network access to wl-api.mf.gov.pl.
---

# Biała Lista Podatników VAT

Fetches official Polish company and VAT status data from the Ministry of Finance (*Ministerstwo Finansów*)
using `scripts/biala_lista.py`. Always outputs structured JSON.

## Running the script

Run from this skill's directory (or use relative path from repo root):

| OS | Command |
|---|---|
| Linux / macOS | `python3 scripts/biala_lista.py <command> …` |
| Windows | `py scripts/biala_lista.py <command> …` (or `python`) |

Zero external dependencies required (standard library only).

## Workflow

1. **Identify the query type:**
   - **NIP (10 digits)**: User provides NIP or asks about a company → `python3 scripts/biala_lista.py nip <nip>`.
   - **Bank Account (26 digits)**: User wants to know who owns an account or if it's safe to pay →
     - Check specific NIP + account match: `python3 scripts/biala_lista.py check <nip> <account>`
     - Find company by account number: `python3 scripts/biala_lista.py account <account>`
   - **REGON (9 or 14 digits)**: User provides REGON → `python3 scripts/biala_lista.py regon <regon>`.
   - **Syntax verification (offline)**: User asks to validate NIP/REGON/IBAN without querying API → `python3 scripts/biala_lista.py validate <value>`.

2. **Historical or specific date:**
   - Add `--date=YYYY-MM-DD` when checking status for a past invoice or event (defaults to today).

3. **Interpret the results:**
   - `statusVat`: `"Czynny"` (active VAT payer — eligible for standard VAT deduction), `"Zwolniony"` (exempt), `"Niezarejestrowany"` (not registered).
   - `accountAssigned`: `"TAK"` (account is registered on the White List — safe for payments > 15,000 PLN) or `"NIE"`.
   - `requestId`: Always note the `requestId` when reporting verification for financial/tax records — it provides legal proof of due diligence (*należyta staranność*) under Polish tax law.

## Commands

| Command | Description | Returns |
|---|---|---|
| `nip <nip> [--date=YYYY-MM-DD]` | Look up company details & VAT status by NIP | `name`, `statusVat`, `isVatActive`, `address`, `krs`, `regon`, `accounts`, `representatives`, `requestId` |
| `check <nip> <account> [--date=YYYY-MM-DD]` | Verify if bank account is on the White List for this NIP | `accountAssigned` (`"TAK"` / `"NIE"`), `isAssigned`, `bank`, `requestId`, `requestDateTime` |
| `account <account> [--date=YYYY-MM-DD]` | Reverse-lookup company associated with a bank account | `accountFormatted`, `bank`, `subjects` list with company details |
| `regon <regon> [--date=YYYY-MM-DD]` | Look up company details by REGON (9 or 14 digits) | Same object as `nip` |
| `validate <value>` | Offline checksum validation for NIP, REGON, or NRB | `type`, `valid`, `formatted`, `bank` (if NRB), `message` |

Field reference and legal context: [references/output.md](references/output.md).

## Exit codes

JSON goes to stdout; errors go to stderr as `{"error": "...", "type": "..."}`.

| Code | Meaning | What to do |
|---|---|---|
| `0` | Success | Use the JSON output |
| `2` | Not found | Subject or account not found in the official registry |
| `64` | Validation / Bad usage | Invalid NIP/REGON/account checksum or bad arguments |
| `69` | Network / API / Rate limit | Retry once; check internet connection |

## Rules

- For B2B transfers above 15,000 PLN gross, always emphasize checking both `statusVat: "Czynny"` and `accountAssigned: "TAK"`.
- If an entity uses virtual accounts (`hasVirtualAccounts: true`), remind the user that `check <nip> <account>` should be used rather than inspecting the static `accounts` list.
- Stripping spaces, dashes, and the `PL` prefix is handled automatically by the script.

© Michell Hoduń (https://github.com/b44x) · MIT · b44x/ai-polish-skills

Similar skills

All skills for Finance and business →

From the same set52

The whole set →
nbp The nbp skill for Claude Code retrieves Narodowy Bank Polski exchange rates and gold prices. It handles currency conversions and invoice tax calculations in PLN. CX Codex +1 ★ 60repo stars filmweb This Claude Code skill retrieves film and TV details from Filmweb. It activates for title or link searches and questions about cast, ratings, release dates, or VOD. CX Codex +1 ★ 60repo stars dzialki The dzialki Claude Code skill finds Polish cadastral parcels through ULDK. Search by a full EGiB identifier, cadastral district and parcel number, or a point’s coordinates. CX Codex +1 ★ 60repo stars odjazdy The odjazdy Claude Code skill finds stops and upcoming bus or tram departures in Gdańsk, Poznań, and Szczecin. Ask about a stop by name or ID to check its board. CX Codex +1 ★ 60repo stars terminy The terminy skill for Claude Code calculates Polish working days, public holidays and deadlines. It handles questions about payment dates, tax schedules and monthly working-time norms. CX Codex +1 ★ 60repo stars nieruchomosci The nieruchomosci Claude Code skill searches Poland’s RCN register for property transactions. Set a coordinate area and filter records by deed date, market, or size. CX Codex +1 ★ 60repo stars sejm This Claude Code skill queries the Polish Sejm’s official API. The agent uses it to look up MPs, voting records, bills and parliamentary interpellations. CX Codex +1 ★ 60repo stars prawo The prawo Claude Code skill looks up Polish laws through the Sejm’s official API. It finds articles, act status, and amendment details. CX Codex +1 ★ 60repo stars

Project sponsors

Companies that keep this analytics open