# date-firme: full guide for AI agents (v0.2.0)

> Romanian company data (date firme) from public registries: ONRC (Registrul Comertului: companies, status, CAEN codes, administrators) and ANAF (VAT / TVA status, yearly financial statements / bilant). Built for AI agents, MCP clients and x402 crawlers. Every paid call is a single HTTP GET (or MCP tool call) paid with x402: no signup, no account, no API key.

Base URL: https://date-firme.dev-box.ro

## Payment (x402 v2)

- Protocol: x402 version 2, scheme `exact`, network base (eip155:8453), asset USD Coin (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913).
- Flow:
  1. Call the endpoint without payment.
  2. You get HTTP 402. The `PAYMENT-REQUIRED` header (base64) and the JSON body contain the PaymentRequired object: `resource` (url, description), `accepts[0]` (amount in USDC atomic units with 6 decimals, payTo, asset, network, maxTimeoutSeconds) and `extensions.bazaar` (input/output schema and examples).
  3. Sign an `exact` payment for `accepts[0]` with an x402 client and repeat the same request with header `PAYMENT-SIGNATURE: <base64 PaymentPayload>`.
  4. On success you get the 2xx JSON plus a `PAYMENT-RESPONSE` header (base64 settlement with the transaction hash).
- You are only charged when the response is 2xx (404 / 400 / 5xx are never settled).
- MCP: same prices. An unpaid `tools/call` returns `isError: true` with the PaymentRequired object in `structuredContent`; resend the call with the payment in `params._meta["x402/payment"]`; the settlement comes back in `result._meta["x402/payment-response"]`.
- Alternative: an operator-issued API key in `Authorization: Bearer <key>` replaces payment.
- Rate limit: 120 requests per minute per IP.

## Free endpoints (no payment, no auth)

- `GET https://date-firme.dev-box.ro/health` - liveness, `{"status":"ok"}`
- `GET https://date-firme.dev-box.ro/llms.txt`, `https://date-firme.dev-box.ro/llms-full.txt` - these guides (text/plain)
- `GET https://date-firme.dev-box.ro/openapi.json` - OpenAPI 3.1; each paid operation has `x-payment-info` (price) and a 402 response; operationId = MCP tool name
- `GET https://date-firme.dev-box.ro/.well-known/x402` - list of paid resources with prices
- `GET https://date-firme.dev-box.ro/.well-known/mcp.json` - MCP registry entry; `https://date-firme.dev-box.ro/.well-known/mcp/server-card.json` - MCP server card with all tools
- `GET https://date-firme.dev-box.ro/robots.txt`

## Typical workflow

1. `search_companies` / `GET /v1/search?q=<name>` -> pick the `cui` of the right company (check county / locality / activa).
2. `company_risk` / `GET /v1/risk/{cui}` for a go/no-go KYB signal; `company_profile` for identity and VAT; `company_financials` for multi-year numbers.
3. Optional: `caen_comparison` with the profile's `cod_caen` to compare with peers; `admin_companies` with an administrator's name to find related companies.

Identifiers: CUI = CIF = Romanian company tax ID (cod unic de inregistrare / cod fiscal), digits, optionally prefixed with RO (VAT form). CAEN = Romanian activity code (4 digits, NACE based). Amounts are in RON (lei).

## Endpoints

### Search Romanian companies (name -> CUI) ($0.002)

- HTTP: `GET /v1/search`  |  MCP tool: `search_companies`
- Use when you only have a company name and need its CUI (cod fiscal) for the other endpoints, or to check that a CUI exists.
- Details: Search the Romanian trade register (ONRC) by company name (denumire firmă), CUI/CIF (RO prefix optional) or registration number (e.g. J40/123/2020). Returns up to 30 matches (cui, name, county, locality, ONRC status, activa), active companies first.
- Parameters:
  - `q` (query, required): Company name (min 2 chars, diacritics optional), CUI/CIF with or without RO prefix, or trade-register number (e.g. J40/123/2020).

Example:

```
curl -i "https://date-firme.dev-box.ro/v1/search?q=dedeman"
# -> 402 + PAYMENT-REQUIRED; pay, then repeat with -H "PAYMENT-SIGNATURE: <base64 payload>"
```

Response 200 (illustrative values):

```json
[
  {
    "activa": true,
    "county": "Bacau",
    "cui": 2816464,
    "locality": "Bacau",
    "name": "DEDEMAN SRL",
    "stare": "funcțiune"
  }
]
```

### KYB risk check for a Romanian company ($0.02)

- HTTP: `GET /v1/risk/{cui}`  |  MCP tool: `company_risk`
- Use when onboarding a supplier or customer, extending credit, or before paying an invoice. Get the CUI first with search_companies.
- Details: KYB risk check for a Romanian company by CUI (tax ID). Returns score 0-100, level low/medium/high and reasons: ONRC insolvency (insolvență), bankruptcy, dissolution, sequestration, criminal case; ANAF/ONRC inactive or deregistered status; latest balance sheet (bilanț: missing, losses, negative equity, falling turnover) and Altman Z'.
- Parameters:
  - `cui` (path, required): CUI / CIF (Romanian company tax ID, cod fiscal): digits with optional RO prefix, e.g. 2816464 or RO2816464. Get it with search_companies.

Example:

```
curl -i "https://date-firme.dev-box.ro/v1/risk/2816464"
# -> 402 + PAYMENT-REQUIRED; pay, then repeat with -H "PAYMENT-SIGNATURE: <base64 payload>"
```

Response 200 (illustrative values):

```json
{
  "an_bilant": 2024,
  "checked": [
    "ONRC status (insolvență/faliment/dizolvare)",
    "ANAF TVA/stare",
    "bilanț ANAF",
    "Altman Z'"
  ],
  "cui": 2816464,
  "denumire": "DEDEMAN SRL",
  "flags": [],
  "level": "low",
  "not_checked": [
    "BPI detaliat (administrator judiciar, termene)",
    "ECRIS (dosare)",
    "datorii ANAF"
  ],
  "score": 0
}
```

### Romanian company profile by CUI ($0.005)

- HTTP: `GET /v1/companies/{cui}`  |  MCP tool: `company_profile`
- Use when you need identity and registration details of a known company: invoicing data, VAT status, legal form or who runs it.
- Details: Romanian company (firmă) profile by CUI/CIF: legal name, address, county, status, registration date and number, legal form (SRL, SA...), main CAEN code, ANAF VAT payer (plătitor TVA) and VAT-on-cash flags, current administrators (ONRC) and Altman Z'.
- Parameters:
  - `cui` (path, required): CUI / CIF (Romanian company tax ID, cod fiscal): digits with optional RO prefix, e.g. 2816464 or RO2816464. Get it with search_companies.

Example:

```
curl -i "https://date-firme.dev-box.ro/v1/companies/2816464"
# -> 402 + PAYMENT-REQUIRED; pay, then repeat with -H "PAYMENT-SIGNATURE: <base64 payload>"
```

Response 200 (illustrative values):

```json
{
  "administratori": [
    {
      "name": "POPESCU ION",
      "role": "administrator"
    }
  ],
  "adresa": "Str. Exemplu 1, Bacau, Bacau",
  "altman_z": {
    "risc": "Scazut",
    "score": 4.06,
    "zona": "Sigura"
  },
  "cod_caen": "4752",
  "cod_postal": "600000",
  "cui": 2816464,
  "data_inregistrare": "1993-01-01",
  "denumire": "DEDEMAN SRL",
  "denumire_caen": "Comerț cu amănuntul al articolelor de fierărie, al articolelor din sticlă și al celor pentru vopsit, în magazine specializate",
  "forma_juridica": "SRL",
  "judet": "Bacau",
  "localitate": "Bacau",
  "nr_reg_com": "J04/0000/1993",
  "platitor_tva": true,
  "stare": "INREGISTRAT din data 01.01.1993",
  "tva_la_incasare": false
}
```

### Financial statements by year (bilant) ($0.01)

- HTTP: `GET /v1/companies/{cui}/financials`  |  MCP tool: `company_financials`
- Use when you need revenue, profit, debt or headcount trends, or a solvency view of a company over several years.
- Details: Yearly financial statements (bilanț ANAF) of a Romanian company by CUI, newest first, in RON: assets, stocks, receivables, cash, debts, equity, capital, turnover (cifra de afaceri), revenue, expenses, gross/net profit, loss, employees, plus Altman Z' and ratios (liquidity, debt/equity, net margin, ROA, turnover per employee). Empty list if no filings.
- Parameters:
  - `cui` (path, required): CUI / CIF (Romanian company tax ID, cod fiscal): digits with optional RO prefix, e.g. 2816464 or RO2816464. Get it with search_companies.

Example:

```
curl -i "https://date-firme.dev-box.ro/v1/companies/2816464/financials"
# -> 402 + PAYMENT-REQUIRED; pay, then repeat with -H "PAYMENT-SIGNATURE: <base64 payload>"
```

Response 200 (illustrative values):

```json
[
  {
    "active_circulante": 2600000000,
    "active_imobilizate": 4200000000,
    "altman_z": {
      "risc": "Scazut",
      "score": 4.06,
      "zona": "Sigura"
    },
    "an": 2024,
    "capital_subscris": 2000000,
    "capitaluri": 4700000000,
    "casa_conturi": 350000000,
    "cheltuieli_totale": 11000000000,
    "cifra_afaceri": 12000000000,
    "creante": 300000000,
    "datorii": 2100000000,
    "nr_angajati": 13000,
    "pierdere_neta": 0,
    "profit_brut": 1200000000,
    "profit_net": 1000000000,
    "ratios": {
      "grad_indatorare": 44.68,
      "lichiditate": 1.24,
      "marja_neta": 8.33,
      "productivitate_angajat": 923076.92,
      "roa": 14.71,
      "rotatie_creante": 40.0
    },
    "stocuri": 1900000000,
    "venituri_totale": 12200000000
  }
]
```

### Industry benchmark by CAEN code ($0.02)

- HTTP: `GET /v1/caen/{code}/comparatie`  |  MCP tool: `caen_comparison`
- Use when you need market leaders or competitors in an industry, or want to place a company against its peers.
- Details: Ranks active Romanian companies with a given main CAEN code by turnover (cifra de afaceri) from their latest balance sheet, with employees, net profit and year. Returns top N (5-20, default 15), the total with data and, if cui is in the top N, its rank (rang_ref).
- Parameters:
  - `code` (path, required): CAEN activity code (cod CAEN, 4 digits), e.g. 4752. A company's main CAEN is in company_profile.cod_caen.
  - `cui` (query, optional): Optional CUI to highlight (is_ref) and rank within the list.
  - `limit` (query, optional): Number of companies to return, 5-20 (default 15).

Example:

```
curl -i "https://date-firme.dev-box.ro/v1/caen/4752/comparatie"
# -> 402 + PAYMENT-REQUIRED; pay, then repeat with -H "PAYMENT-SIGNATURE: <base64 payload>"
```

Response 200 (illustrative values):

```json
{
  "caen": "4752",
  "firme": [
    {
      "activa": true,
      "an": 2024,
      "angajati": 13000,
      "ca": 12000000000,
      "cui": 2816464,
      "denumire": "DEDEMAN SRL",
      "is_ref": true,
      "judet": "Bacau",
      "localitate": "Bacau",
      "profit": 1000000000,
      "rank": 1,
      "stare": "funcțiune"
    }
  ],
  "rang_ref": 1,
  "total": 2400
}
```

### Companies of a named administrator ($0.01)

- HTTP: `GET /v1/admins/{name}/companies`  |  MCP tool: `admin_companies`
- Use when you need a person's other business affiliations: related parties, conflicts of interest or due diligence on a director.
- Details: Lists Romanian companies (up to 200) where a person is currently registered as administrator or representative in ONRC public data. Exact match on the full name, case- and diacritics-insensitive. Returns cui, company name (denumire), county and role (status_label).
- Parameters:
  - `name` (path, required): Full name of the person as registered in ONRC (min 3 chars), e.g. POPESCU ION. URL-encode spaces in the HTTP path.

Example:

```
curl -i "https://date-firme.dev-box.ro/v1/admins/POPESCU%20ION/companies"
# -> 402 + PAYMENT-REQUIRED; pay, then repeat with -H "PAYMENT-SIGNATURE: <base64 payload>"
```

Response 200 (illustrative values):

```json
{
  "query": "POPESCU ION",
  "results": [
    {
      "county": "Cluj",
      "cui": 12345678,
      "denumire": "EXEMPLU SRL",
      "status_label": "administrator"
    }
  ],
  "total": 1
}
```


### company_risk flag codes

Each flag adds points; score = sum capped at 100; level: low < 25 <= medium < 55 <= high.

- `insolventa` (70): ONRC status insolvency / reorganization / bankruptcy (insolventa, faliment, Legea 85/2014)
- `status_critic` (60): deregistered (radiata), inactive, suspended, dissolved or in liquidation (ANAF/ONRC status)
- `capitaluri_negative` (20): negative equity in the latest balance sheet
- `altman_pericol` (25) / `altman_gri` (10): Altman Z' in the distress / grey zone
- `sechestru` (15): sequestration recorded at ONRC
- `urmarire_penala` (15): criminal proceedings recorded at ONRC
- `firma_noua` (10): registered less than a year ago
- `fara_bilant` (10): no balance sheet available
- `pierdere` (10): net loss in the latest year
- `scadere_cifra_afaceri` (10): turnover fell more than 30% versus the previous year

The report also returns `checked` and `not_checked` so you know what the absence of a flag means.

## MCP

- Endpoint: `https://date-firme.dev-box.ro/mcp` (Streamable HTTP, JSON-RPC over POST, JSON responses; no SSE).
- Client config:

```json
{"mcpServers":{"date-firme":{"url":"https://date-firme.dev-box.ro/mcp"}}}
```

- Tools: search_companies, company_risk, company_profile, company_financials, caen_comparison, admin_companies. All are read-only and idempotent; each has an outputSchema. Text content = the HTTP JSON body; structuredContent = the same body (array results are wrapped as `{"results": [...]}` for search_companies and `{"years": [...]}` for company_financials).
- Registry: io.github.iorpaul3/date-firme

## Limits (be honest with your users)

- Insolvency comes only from ONRC status codes; there is no BPI (Buletinul Procedurilor de Insolventa) detail: no judicial administrator, deadlines or creditor claims.
- No court files (ECRIS / portal.just.ro dosare).
- No ANAF tax debts (obligatii fiscale restante) and no e-Factura data.
- Financial data exists only for companies that filed balance sheets with ANAF and for the years loaded in the database; some fields can be null; `/financials` can return an empty list.
- Administrators: current representatives from ONRC open data only, matched by exact full name (case and diacritics insensitive).
- Search returns at most 30 results; admin_companies at most 200; caen_comparison 5-20 companies and only active ones with turnover data.
- Example responses in this guide use illustrative values; field names and types match the real responses (see /openapi.json for full schemas).

## Links

- OpenAPI: https://date-firme.dev-box.ro/openapi.json
- x402 discovery: https://date-firme.dev-box.ro/.well-known/x402
- MCP: https://date-firme.dev-box.ro/mcp
- Short guide: https://date-firme.dev-box.ro/llms.txt