# Open Data Proxy — full reference

Pay $0.01 USDC per call to validate IBANs, EU VAT numbers and Dutch postcodes, and to query CBS housing, company, domain and EU sanctions data on Base Mainnet.

## Payment model

$0.01 USDC per call on Base Mainnet; payment issues a 1-hour unlimited ticket.

## Data & sources

Sourced live from CBS StatLine (table 85773NED), BAG postcode data, EU VIES, RDAP, and the EU consolidated sanctions list. VIES lookups are cached for 24h.

## Endpoints

## /health (GET)

Unprotected health check. Returns 200 without payment.

Response (JSON):

```json
{
  "status": "ok",
  "service": "open-data-proxy",
  "timestamp": "2026-01-01T00:00:00Z"
}
```

## /iban (GET)

Use GET /iban?value=… to check checksum validity and retrieve bank name, country and BIC.

Price: $0.01 USDC

Example: `GET /iban?value=NL91ABNA0417164300`

Input parameters:

- `value` — example: `NL91ABNA0417164300`

Response (JSON):

```json
{
  "iban": "NL91ABNA0417164300",
  "valid": true,
  "bank": "ABN AMRO",
  "country": "Netherlands",
  "bic": "ABNANL2A",
  "checksum": "valid"
}
```

## /vat (GET)

Use GET /vat?value=… to validate a VAT number against the EU VIES service. Responses are cached for 24h.

Price: $0.01 USDC

Example: `GET /vat?value=NL852378361B01`

Input parameters:

- `value` — example: `NL852378361B01`

Response (JSON):

```json
{
  "valid": true,
  "input": "NL852378361B01",
  "registeredName": "Example B.V.",
  "country": "NL",
  "vatNumber": "852378361B01",
  "requestDate": "2026-01-01T00:00:00Z"
}
```

## /postcode (GET)

Use GET /postcode?code=…&number=… to expand a Dutch postcode into street, city, municipality, province and coordinates.

Price: $0.01 USDC

Example: `GET /postcode?code=1012AB&number=1`

Input parameters:

- `code` — example: `1012AB`
- `number` — example: `1`

Response (JSON):

```json
{
  "input": "1012AB",
  "houseNumber": "1",
  "street": "Stadhouderskade",
  "city": "Amsterdam",
  "municipality": "Amsterdam",
  "province": "Noord-Holland",
  "lat_lon": "52.3633,4.8823",
  "valid": true
}
```

## /cbs/housing-snapshot (GET)

Use GET /cbs/housing-snapshot?postcode=… to read median WOZ value, transaction volume and price trend from CBS table 85773NED.

Price: $0.01 USDC

Example: `GET /cbs/housing-snapshot?postcode=1012AB`

Input parameters:

- `postcode` — example: `1012AB`

Response (JSON):

```json
{
  "input": "1012AB",
  "medianWOZ": 450000,
  "transactionVolume": 120,
  "priceTrend": 3.5,
  "postcode": "1012AB",
  "timestamp": "2026-01-01T00:00:00Z"
}
```

## /cbs/enrich (GET)

Use GET /cbs/enrich?name=…&city=… to assemble CBS open data and a DNS heuristic into a company profile (BAG address, SBI codes, employee bracket). Not KVK-accurate.

Price: $0.01 USDC

Example: `GET /cbs/enrich?name=Acme&city=Amsterdam`

Input parameters:

- `name` — example: `Acme`
- `city` — example: `Amsterdam`

Response (JSON):

```json
{
  "input": {
    "name": "Acme",
    "city": "Amsterdam"
  },
  "employeeBracket": "unknown",
  "note": "Assembly of open CBS data + DNS heuristics; not KVK-accurate"
}
```

## /domain/bundle (GET)

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.

Price: $0.01 USDC

Example: `GET /domain/bundle?domain=example.com`

Input parameters:

- `domain` — example: `example.com`

Response (JSON):

```json
{
  "trustScore": 90,
  "mailGrade": {
    "grade": "A",
    "score": 100
  },
  "sslInfo": {
    "daysToExpiry": 30
  },
  "assessmentDate": "2026-01-01T00:00:00Z"
}
```

## /sanctions (GET)

Use GET /sanctions?name=… to fuzzy-match a name against the EU consolidated sanctions list and return a confidence score plus the matched entity.

Price: $0.01 USDC

Example: `GET /sanctions?name=Putin`

Input parameters:

- `name` — example: `Putin`

Response (JSON):

```json
{
  "input": "Putin",
  "match": true,
  "confidence": "high",
  "matched": {
    "name": "Putin",
    "type": "person",
    "category": "political"
  },
  "listSize": 6
}
```

## Payment instructions

1. Call the endpoint without a ticket to receive a `402 Payment Required`.
2. Pay $0.01 USDC on Base Mainnet (chainId 8453) to `0x72b74c7232d2de278aac391cc72d6e51fa0defcb`.
3. Present the transaction to the proxy at https://x402.thesoulnetwork.eu.
4. Send the returned ticket as `Authorization: Bearer <ticket>` on every call until it expires (1 hour).