# Agent instructions — Open Data Proxy

Base URL: https://cbs.thesoulnetwork.eu

This host sells normalized open data. The public HTML, the PDFs and the
raw JSON of The World Upside Down stay free at
https://thesoulnetwork.eu/upsidedown/. This host sells the normalized,
provenance-joined rows.

## Before you spend

Ask your owner before the first payment, and before raising your budget.
Suggested owner cap: $0.50 per day (about 50 calls). Set your own cap and stop when it is reached.
If a request would exceed your owner's cap, stop and ask. Do not open a
second wallet or raise the cap yourself.

## What one payment buys

- One network pass: $0.01 USDC, 3600 seconds.
- The pass works on every gated endpoint on this host and on the relay.
- While the pass is valid, calls are unlimited. The pass is a fixed
  price for one hour; it is not metered per call or per byte.
- The pass is not refundable.

## Price

| Field | Value |
|---|---|
| Network | base-mainnet (eip155:8453) |
| Asset | USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
| Amount | `10000` USDC units = $0.01 (6 decimals) |
| payTo | `0x72b74c7232d2de278aac391cc72d6e51fa0defcb` |
| Ticket | 3600 seconds |
| Header | `Authorization: Bearer <ticket>` |

## Flow

1. Call a gated route, for example `GET https://cbs.thesoulnetwork.eu/upsidedown/v1/dataset`.
2. Receive `402 Payment Required` with a base64 `PAYMENT-REQUIRED` header.
3. Decode the header and read `accepts[0]`.
4. Sign the EIP-3009 authorization for that exact amount, asset and payTo.
5. Retry the same request with `PAYMENT-SIGNATURE: <base64 payload>`.
6. Read the `X-Ticket` response header and `PAYMENT-RESPONSE` settlement.
7. Send `Authorization: Bearer <ticket>` on later calls until it expires.
8. On a new 402 after expiry, stop and ask your owner before paying again.

## Endpoints

- `GET /iban` — Use GET /iban?value=… to check checksum validity and retrieve bank name, country and BIC.
- `GET /vat` — Use GET /vat?value=… to validate a VAT number against the EU VIES service. Responses are cached for 24h.
- `GET /postcode` — Use GET /postcode?code=…&number=… to expand a Dutch postcode into street, city, municipality, province and coordinates.
- `GET /cbs/housing-snapshot` — Use GET /cbs/housing-snapshot?postcode=… to read median WOZ value, transaction volume and price trend from CBS table 85773NED.
- `GET /domain/bundle` — Use GET /domain/bundle?domain=… to bundle RDAP registration data, MX/SPF/DMARC mail grading, SSL expiry and a tech-stack heuristic into one call.
- `GET /sanctions` — Use GET /sanctions?name=… to fuzzy-match a name against the EU consolidated sanctions list and return a confidence score plus the matched entity.
- `GET /upsidedown/v1/dataset` — Use GET /upsidedown/v1/dataset to fetch every published country as long-format rows (country × metric) with unit, currency, data year, status, publisher, source URL and calculation.
- `GET /upsidedown/v1/dataset.csv` — Use GET /upsidedown/v1/dataset.csv to download the same normalized rows as CSV: country, iso, metric, label, value, daily_value, unit, currency, data_year, source_year, status, publisher, source_url, calculation, note.
- `GET /upsidedown/v1/countries/{iso}` — Use GET /upsidedown/v1/countries/{iso} to fetch one published country as normalized rows plus its country metadata (currency, data year, fact-check state, publication date).

## Errors

| Status | Error | Meaning | Action |
|---|---|---|---|
| 402 | `payment_required` | No ticket, or the ticket expired. | Pay once, or reuse a valid ticket. |
| 402 | `coming_soon` | The endpoint does not accept payment yet. | Do not pay; use a billable route. |
| 404 | `not_found` | The route or country does not exist. | Do not pay; fix the request. |
| 502 | `origin_unavailable` | The public origin did not answer. | Retry later; do not pay for a failed read. |

Settlement errors come from the payment proxy at https://x402.thesoulnetwork.eu: `402 invalid_payment` and `402 payment_already_used`.

## Cost rules

- A ticket is valid for one hour from settlement.
- One ticket covers the whole network, not one endpoint.
- The price is per pass, not per call or per byte.

## License

Numbers are quoted from the public sources in each row. Attribution: The World Upside Down — https://thesoulnetwork.eu/upsidedown/. No warranty; figures are as published.

Support: info@thesoulnetwork.eu

## Machine links

- `https://cbs.thesoulnetwork.eu/llms.txt`
- `https://cbs.thesoulnetwork.eu/llms-full.txt`
- `https://cbs.thesoulnetwork.eu/openapi.json`
- `https://cbs.thesoulnetwork.eu/.well-known/x402`