Sirenic Examples

> 🚀 Sirenic launched on Product Hunt in July 2026: https://www.producthunt.com/products/sirenic

Working examples for Sirenic — official French and

European company data for AI agents: company lookup by name or SIREN, full

company profiles, KYB verification and due-diligence files, AML sanctions

screening, annual accounts and financial statements, default-risk scoring and

company monitoring, from the French company registry (INSEE Sirene, INPI RNE)

and official registers across 12 European countries. Pay-per-call in **USDC or

EURC** via the x402 protocol:

no account, no API key — your agent pays each request on Base. Every paid response is

Ed25519-signed and verifiable offline

(recipe) — and carries

its per-block provenance: which official register each block came from, its

licence, its version and its `as_of` date, with the exact meaning of that date

(upstream official publication, Sirenic ingestion, or live consultation).

Verify the signature, then read the provenance: your agent can prove to an

auditor what it knew when it paid. Codes are resolved for free at

`/v1/provenance/registres`.

• Landing & pricing: https://api.sirenic.eu
• OpenAPI: https://api.sirenic.eu/openapi.json
• For LLMs: https://api.sirenic.eu/llms.txt
• MCP server: `https://api.sirenic.eu/mcp` (streamable HTTP)
• A2A agent: `POST https://api.sirenic.eu/a2a` (JSON-RPC, a2a-x402 payment

extension) — card at `https://api.sirenic.eu/.well-known/agent-card.json`

Data sources: INSEE Sirene / INPI RNE and other official registers, open

licenses (Etalab 2.0, NLOD, CC-BY 4.0, OGL, CC0). Data is redistributed

as published — every response carries `source` and `disclaimer` fields.

Quickstart 0 — name → SIREN, for free (no wallet, no account, no key)

Every other call takes a SIREN. Getting one from a name costs nothing:

curl -s "https://api.sirenic.eu/v1/suggestions?q=carrefour"

Up to 5 matches, each with `siren`, `denomination`, `code_postal`, `commune`,

`code_naf` and `actif`. Source: the official INSEE Sirene register (open data).

Drop it straight into a form's autocomplete, or let your agent resolve the name

before it decides what to buy. Quota: 2,000 calls per day per IP.

It matches the start of the registered name, then whole words (`agricole`

finds CRÉDIT AGRICOLE) — no typo tolerance and no match-confidence score. For

those, `GET /v1/recherche` costs $0.002. Then pick your paid call below.

Quickstart 1 — "Can you safely invoice or pay this company?"

One call, three answers: is the supplier still active, is its VAT number valid

today, and is that IBAN a real account at an identified bank. Start with the

quote — free, no wallet, no account:

curl -i "https://api.sirenic.eu/v1/facturation/dossier?siren=552032534&iban=FR1420041010050500013M02606"

Then pay the $0.03 and get the file, with a deterministic verdict:

const res = await payingFetch(
  "https://api.sirenic.eu/v1/facturation/dossier?siren=552032534&iban=FR1420041010050500013M02606",
);
const dossier = await res.json();
dossier.verdict.pret_a_facturer; // true | false
dossier.verdict.raisons;         // closed list: entreprise_cessee, tva_invalide_vies, iban_invalide…

`payingFetch` is the six-line x402 wrapper of Quickstart 3. Belgium and Poland:

`GET /v1/eu/facturation/dossier?pays=&id=&iban=` (same price, same verdict).

The response is Ed25519-signed and carries its provenance inside the signed

bytes — `examples/verify-invoice-file.ts`

turns one call into an audit file that still re-verifies offline years later.

Why this matters in 2026: see the section below.

Quickstart 2 — see a payment quote (no wallet needed)

curl -i "https://api.sirenic.eu/v1/entreprise/552032534" -H "Accept: application/json"

You get `HTTP 402` with the x402 payment requirements in the

`PAYMENT-REQUIRED` header and a JSON body. Each quote carries **two payment

options at the same numeric amount** — USDC (first, the default for existing

clients) or EURC — with the official Circle contracts, receiving address and

network.

Quickstart 3 — pay and call in ~10 lines (TypeScript)

npm install @x402/fetch @x402/core @x402/evm viem

import { privateKeyToAccount } from "viem/accounts";
import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";

const account = privateKeyToAccount(process.env.TEST_WALLET_KEY as `0x${string}`);
const client = new x402Client();
registerExactEvmScheme(client, { signer: account });
const payingFetch = wrapFetchWithPayment(fetch, client);

const res = await payingFetch("https://api.sirenic.eu/v1/entreprise/552032534");
console.log(await res.json()); // paid, settled, delivered

`TEST_WALLET_KEY` is the private key of your client test wallet (the

payer). The server never holds any key. The `exact` scheme uses signed

authorizations, so the client pays no gas.

Quickstart 4 — plug into Claude / Cursor (MCP)

Claude Code:

claude mcp add --transport http sirenic https://api.sirenic.eu/mcp

Cursor / any MCP client (`mcpServers` config):

{ "mcpServers": { "sirenic": { "url": "https://api.sirenic.eu/mcp" } } }

76 tools are exposed — including TWO FREE ones: suggest_company_names (type a company name, get its SIREN — start here) and detect_company_identifiers (paste any text, get SIREN/SIRET/VAT/LEI with the right call to make). Plus verify_iban_bank. Search with 0-1 confidence scores, company profiles,

KYB files, an à-la-carte company file where you pick the blocks and pay only for those, a $1 company-intelligence report, sanctions screening, AMF

regulator alerts, **regulatory authorisations by SIREN (EBA PSD2 register,

EIOPA, ARCEP)**, EU financial authorisations (ESMA), industrial risk

(Seveso/ICPE), lobbying register, EU procurement awards (TED), **watchlists

with daily checks and Ed25519-signed webhooks**, financials, capital structure, sector benchmarks, failure-risk score, Belgian annual accounts…). Each tool accepts

an optional `x_payment` parameter: without it you get the 402 quote; sign it

with an x402 client and call again. Every tool declares an output schema

and returns `structuredContent`, plus MCP annotations (read-only vs. state-

changing), so a client can type-check responses instead of parsing prose. The

quote you get back is the signable x402 payment requirements

(`{x402Version, accepts[]}`) — an agent can pay entirely from MCP, without

touching the REST API.

Quickstart 5 — A2A (Agent2Agent)

Sirenic is also an A2A 1.0 agent with the official crypto payment extension

(a2a-x402). Discover it from the card, send a JSON data part, get the quote

as task metadata, pay on the same task:

curl -s https://api.sirenic.eu/.well-known/agent-card.json -H "A2A-Version: 1.0"
npx tsx examples/a2a.ts   # quote for free; add TEST_WALLET_KEY to pay

Quickstart 6 — LangChain & CrewAI SDKs

Ready-made paying tools with a hard price cap (sdk/typescript,

sdk/python):

import { sirenicTools } from "sirenic-agents";           // LangChain.js
const tools = sirenicTools({ walletKey, maxPriceUsd: 0.25 });

from sirenic_agents import SirenicClient, build_crewai_tools   # CrewAI / LangChain
tools = build_crewai_tools(SirenicClient(wallet_key=key, max_price_usd=0.25))

CrewAI can also use Sirenic's MCP server directly, no SDK:

`Agent(..., mcps=["https://api.sirenic.eu/mcp"])`.

Verify a supplier before you pay — the 2026 e-invoicing window

Three dates make this urgent, and only one of them is French:

• France — September 1, 2026. Every company subject to VAT must be able to

RECEIVE electronic invoices; issuance is phased (large and mid-size companies

September 2026, SMEs and micro-businesses September 2027). Art. 91, Loi de

finances 2024.

• Belgium — in force since January 1, 2026. Structured e-invoicing is

mandatory between Belgian VAT-registered businesses.

• Poland — no deadline, a standing tax rule. Paying more than PLN 15,000

into an account the supplier has *not* declared in the official White List

(wykaz podatników VAT) costs the buyer the deduction and exposes it to joint

liability for the VAT (art. 117ba Ordynacja podatkowa).

Five routes cover it — no account, no API key:

One free call to `/v1/reperer?texte=` tells your agent which of them to use on

any raw text. The verdict's reasons are a closed list (`entreprise_cessee`,

`tva_invalide_vies`, `iban_invalide`…), so an agent branches on codes instead of

parsing prose — and a VIES outage yields an honest `tva_non_verifiable`, never a

false invalid.

Every one of these responses is Ed25519-signed, and the **provenance travels

inside the signed bytes**: which official register served each block, and its

`as_of` date. Verify the signature, then read the provenance — that is an audit

trail you can hand to an accountant.

`examples/verify-invoice-file.ts` writes one

to disk and re-verifies it from the files alone.

Two things this is not:

• Not a check of the account holder's name. Sirenic validates the IBAN and

identifies the bank from official registers; it never confirms that the

account belongs to the company you are about to pay.

• Not an accredited platform (PDP). Sirenic does not issue, transmit or

route any invoice, and does not confirm a recipient's registration on the PPF

or any accredited platform. It gives your agent the checks to run *before* the

invoice exists.

Endpoints and prices (USDC or EURC per call, same amount)

> A real sample response for every endpoint below is in

> `examples/responses/` — dated, truncated to one item per

> array, and identical to what the OpenAPI spec and the x402 quote declare.

Don't clean up the query yourself. Search parameters (`?q=`, `?nom=`) accept

what an agent naturally produces: quotes, punctuation and unsupported characters

are stripped, not rejected — no 400 for a stray quote. Paste an identifier as

you found it and it resolves directly: `SIREN : 552 032 534`, a 14-digit SIRET or

an FR VAT number all land on the right company. A 400 comes back only when nothing

searchable is left — and no error response is ever billed.

Free: `GET /` (landing), `GET /v1/suggestions?q=` (**company-name autocomplete →

SIREN**, up to 5 matches, 2,000 calls/day/IP),

`GET /preview/entreprise/55203253400646` (sample

response), `GET /v1/reperer?texte=` (detect SIREN/SIRET/VAT/LEI in any text,

with the suggested paid call and its price), `GET /openapi.json`,

`GET /llms.txt`, `GET /healthz`; watchlist

status `GET /v1/surveillance/{token}` and stop `…/{token}/arreter` (the token

returned at creation is the capability — no account).

In this repo

• `examples/smoke-bodacc-2026-08-11.ts` — buy the BODACC criteria search for real (3 purchases, $0.09) and check that no court-appointed administrator is ever named in the response.
• `examples/smoke-dossier-2026-08-11.ts` — buy the à-la-carte company file for real (4 purchases, ~$0.32) and check the quote matches the blocks asked for.
• `examples/smoke-eu-recherche-reprise-2026-08-25.ts` — re-buy the European search for Norway after it answered `503 registres_muets` ($0.003): the script names the three outcomes it can measure — a real result, a paid empty answer, or a persistent 503 — and exits non-zero on the last two, because "we retried and it looked fine" is not a measurement.
• `examples/smoke-entrees-clementes-2026-08-30.ts` — buy the agent-shaped queries for real ($0.006): quotes around a name are served, a spaced and labelled SIREN resolves directly, and two negatives — a euro amount must not resolve to a company, and a 400 must not be billed while still recording which rule and which field refused it.
• `examples/suggestions.ts` — the free name → SIREN autocomplete, and the checks that prove it stays free (no wallet needed: `npx tsx examples/suggestions.ts`).
• `examples/quote.sh` — inspect a 402 quote with curl.
• `examples/pay-and-call.ts` — pay one request end to end.
• `examples/verify-invoice-file.ts` — verify a supplier before you pay, and keep the proof (~$0.03): buy the invoicing file, verify its signature offline, read the `pret_a_facturer` verdict and its provenance only once authenticated, then write a timestamped audit folder (raw bytes, signature, public key, `LISEZ-MOI.md`) and re-verify it from those files alone.
• `examples/verify-signature.ts` — the full audit loop: verify the Ed25519 signature of a paid response offline, then read its per-block provenance (official register + `as_of` date) from inside the signed bytes (~$0.02).
• `examples/responses/` — what you actually get back: one

real, dated sample per paid endpoint, truncated to one item per array. The same

samples are served by the API itself, in the OpenAPI spec, in the x402 payment

quote and in `llms.txt` — so the contract you read is the contract you get.

• `examples/smoke-surveillance-durees-2026-08-11.ts` — buy a 90-day and a 365-day watchlist for real (~$0.685), renew one at a different duration, and check that an out-of-range duration and an over-long renewal are both refused without a debit.
• `examples/smoke-test.ts` — pay and call the core paid endpoints once (~46 calls across the 79-route catalogue, USDC and/or EURC; the watchlist it creates is stopped again for free). Country deep-dive sub-routes have their own dedicated smokes in this folder.
• `examples/agent-demo.ts` — a small autonomous agent that searches, pays and reads profiles.
• `examples/mcp-setup.md` — MCP configuration for Claude, Cursor and generic clients.
• `examples/a2a.ts` — call Sirenic as an A2A agent (quote for free, then pay on the same task via the a2a-x402 extension).
• `tutorial-kyb-agent/` — Build a KYB agent in 20 lines.
• n8n community node — moved to its own repository (n8n verification requires credentials/ at the repo root): https://github.com/sirenic-eu/n8n-nodes-sirenic — `npm i n8n-nodes-sirenic`

Test wallet setup

1. Create a throwaway wallet (e.g. in MetaMask) and export its private key.

2. Fund it with a couple of dollars of USDC on Base (any exchange can withdraw to Base network).

3. `export TEST_WALLET_KEY=0x...` — never commit it anywhere.

Sirenic settles on Base mainnet.

Disclaimer

Sirenic redistributes official open data as published (Etalab 2.0 and other

open licenses). It does not guarantee accuracy or completeness, and outputs

(including sanctions screening and AI summaries) are decision aids — not

legal, financial or compliance advice.

License: MIT.