# Integration kit

For broker-software vendors, and anyone else putting RiskRouter behind their own product. Each
example does the same five things, in the language your product is probably written in, with no
dependencies beyond the language's own standard library:

1. **Price** a configuration. The server prices it; your code never does. No key is sent, so
   nothing is recorded.
2. **Record** a quote against your key, with an `Idempotency-Key`, then retry with the same key and
   get the same entry back. A double-click or a network retry can never record twice.
3. **Record evidence** of a regulated decision without sending it: a broker's demands-and-needs
   note is salted and hashed on your side; only the SHA-256 reaches us.
4. **Export** your entries, the chain they sit in and the signed head.
5. **Prove** one evidence entry against the signed head.

| Language | Files | Run |
| --- | --- | --- |
| Python 3.8+ | `python/riskrouter.py`, `python/demo.py` | `python3 demo.py` |
| PHP 8.1+ (curl) | `php/RiskRouter.php`, `php/demo.php` | `php demo.php` |
| C# (.NET 8) | `dotnet/RiskRouter.cs`, `dotnet/Program.cs` | `dotnet run` |
| Java 17+ | `java/RiskRouterDemo.java` | `java RiskRouterDemo.java` |

Every example reads `RISKROUTER_API_KEY` (take a sandbox key in seconds at
<https://riskrouter.eu/integrate#get-a-key>) and optionally `RISKROUTER_BASE` (defaults to
`https://api.riskrouter.eu`). Keys belong on your server, never in a browser.

## The reference app

`reference-app/app.py` is a one-file "broker desk": configure cover, write the demands-and-needs
note, price and record. The note and the customer's name stay in the app's own data file; only the
note's salted fingerprint is recorded. "Evidence pack" bundles, for one customer, the note, its
salt, the single-entry proof of the quote and the Merkle proof of the note.
`reference-app/check_pack.py` checks a pack offline with the independent Python verifier:

```
OK    the note and its salt produce the recorded digest
OK    the note's digest is entry 4 of the evidence log
OK    the quote is entry 6 of the quote ledger, linked to its head
OK    the evidence head is signed
OK    the quote ledger head is signed
```

That is IDD Article 20 evidence a broker can hand to an inspector, for one customer, without
revealing any other, and without RiskRouter ever holding the personal data in it.

## Tested, not just written

`npm run test:kit` runs every example and the reference app against the real Worker on an
in-memory backend that chains, replays and proves like the real schema
(`RISKROUTER_BACKEND=fake node tests/harness.mjs` serves the same thing on port 8787 for your own
experiments). Every file the examples write is checked by both independent verifiers, and the test
fails if the customer's name or note reaches the backend. CI runs it on every push.

Format and proofs: <https://riskrouter.eu/spec>. API: <https://riskrouter.eu/docs>.