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 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

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

Endpoints

Route	What it returns
`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