# StorkHost pl-by-tools

> Deterministic Polish and Belarusian data tools for agents: validate and parse Polish identifiers (PESEL with birth date and sex, NIP, REGON 9/14, KRS, Polish IBAN with bank name and BIC from the embedded NBP list), transliterate Belarusian between Cyrillic and Łacinka or the official 2023 national romanization, and spell numbers and currency amounts in Belarusian or Polish words with correct case and agreement. Pure computation, no data stored. Pay per call with x402 (USDC on Base); no API key, no signup. Hosted on StorkHost (storkhost.cloud), the agent-first cloud.

Base URL: https://shost-app-5qmg7cskqe6b0sux9cbczu.apps.storkhost.cloud

## Paid endpoints (x402, USDC on Base, no API key)

- POST https://shost-app-5qmg7cskqe6b0sux9cbczu.apps.storkhost.cloud/v1/pl/validate — $0.002 per call — Validate and parse Polish identifiers: PESEL (checksum, birth date, sex), NIP (checksum, with or without the PL prefix and dashes), REGON (9 and 14 digits, incl. the parent REGON check), KRS (format) and Polish IBAN/NRB (mod-97, settlement-number check digit, bank name + BIC from the embedded NBP list). Type auto-detected or given; up to 100 values per call.
- POST https://shost-app-5qmg7cskqe6b0sux9cbczu.apps.storkhost.cloud/v1/be/translit — $0.002 per call — Transliterate Belarusian (treated as its own language, not Russian) between Cyrillic and the classic Łacinka (ć ś ź ń, ł/l, ŭ, je/ie rules; both directions), or romanize with the official 2023 national Instruction (geographic names, no diacritics), the 2007 national system, or passport style. Up to 20,000 characters per call.
- POST https://shost-app-5qmg7cskqe6b0sux9cbczu.apps.storkhost.cloud/v1/numwords — $0.002 per call — Spell a number (|n| < 10^15) in Belarusian or Polish words, nominative or genitive, with grammatical gender (адзін/адна/адно, jeden/jedna/jedno), or a currency amount (BYN, PLN, EUR, USD) with correctly agreeing nouns: сто дваццаць тры рублі сорак пяць капеек / sto dwadzieścia trzy złote czterdzieści pięć groszy.

Unpaid call -> HTTP 402: v1 requirements in the JSON body, v2 PaymentRequired (base64 JSON) in the PAYMENT-REQUIRED header. Sign a USDC EIP-3009 TransferWithAuthorization for the exact amount to payTo 0x7e76fF9A43cd3c0202E45682366EF37db9b0ADdB and retry with PAYMENT-SIGNATURE (v2) or X-PAYMENT (v1). Settlement is done by the facilitator https://facilitator.payai.network; you pay no gas. Invalid input is rejected with 400 before any charge; a failed settlement returns 402 and no result.

## POST /v1/pl/validate

{"value":"PL61 1020 1026 0000 0000 0000 0000"}  or  {"values":["...","..."],"type":"auto"}
- type: auto (default) | pesel | nip | regon | krs | iban. Auto: 11 digits = PESEL, 10 = NIP (KRS if it starts with 0), 9/14 = REGON, PL+26 or 26 digits = IBAN/NRB, 'KRS ...' = KRS.
- PESEL: checksum, birthDate (1800-2299 month offsets), sex. NIP: checksum, PL prefix/dashes ok, euVat. REGON: 9 and 14 digits (14 also checks the parent 9). KRS: format only (no checksum exists). IBAN: mod-97, settlement-number check digit, bank name + BIC from the embedded NBP EWIB list (as of 2026-10-01).
- Result: valid, errors[], warnings[], parsed fields. Up to 100 values per call.

## POST /v1/be/translit

{"text":"Беларусь, Магілёў, сям'я","scheme":"lacinka"} -> {"text":"Biełaruś, Mahiloŭ, siamja"}
- scheme lacinka: classic Łacinka (ł/l, ć ś ź ń, ŭ, ch, č š ž; je/ie, ja/ia; ля = la). direction "lat2cyr" converts Łacinka back to Cyrillic.
- scheme national2023: official 2023 Instruction for geographic names (no diacritics): Магілёў -> Magiliow, Беларусь -> Bielarus, плошча -> ploshcha.
- scheme national2007: the previous official system: Гомель -> Homieĺ, Магілёў -> Mahilioŭ.
- scheme passport: passport-style names: Ціханоўская -> Tsikhanouskaya, Юлія -> Yuliya.
- Belarusian only (і, ў; no и/щ/ъ — Russian letters get a warning). Taraškievica spelling works.

## POST /v1/numwords

{"number":123,"lang":"be"} -> "сто дваццаць тры"
{"number":"123.45","lang":"pl","currency":"PLN"} -> "sto dwadzieścia trzy złote czterdzieści pięć groszy"
- lang be | pl; case nom | gen; gender m | f | n (адна/дзве, jedna/dwie); |n| < 10^15.
- currency BYN | PLN | EUR | USD; minor words | digits | omit.

## Discovery

- OpenAPI: https://shost-app-5qmg7cskqe6b0sux9cbczu.apps.storkhost.cloud/openapi.json
- x402 resources: https://shost-app-5qmg7cskqe6b0sux9cbczu.apps.storkhost.cloud/.well-known/x402

## Hosted on StorkHost

This API runs on StorkHost (https://storkhost.cloud), an agent-first cloud: agents sign up with a wallet signature, top up with x402 and deploy containers, functions and static sites per second. Docs: https://api.storkhost.cloud/llms.txt