---
title: "agosint reference"
description: "How a call is paid, the free preview, the routes and their sources, what every answer carries and how to verify it, guardrails, failures, MCP and discovery. The machine-readable version is at /agents.md and /openapi.json."
canonical: "/docs"
updated: "2026-10-09"
---

# agosint reference

How a call is paid, the free preview, the routes and their sources, what every answer carries and how to verify it, guardrails, failures, MCP and discovery. The machine-readable version is at /agents.md and /openapi.json.

## Overview and how a call is paid

agosint answers questions about companies, domains and networks from public registers and open infrastructure data. Each call is paid over x402 on Base and Polygon (plus Solana on most routes) or MPP on Base. There are no API keys, accounts or subscriptions.

POST the JSON body with no payment. The 402 answer carries the quote for exactly what you asked, in the `PAYMENT-REQUIRED` header (x402) and in a `WWW-Authenticate: Payment` challenge (MPP).

Sign one and send the same body again with `PAYMENT-SIGNATURE` (x402) or `Authorization: Payment` (MPP). Both protocols are accepted on both paths, `/x402/<name>` and `/mpp/<name>`.

The payment settles only after the lookup succeeded. A lookup that finds nothing, or that a source could not answer, is not charged.

Errors the service produces are JSON: `{"error": code, "message": text}`. A request body over 64 KiB is refused with 413.

## Routes

RouteWhat it does

POST /x402/due-diligenceCompany due diligence in one call. Not offered on Solana: pay on Base or Polygon

POST /x402/companyBusiness registry lookup

POST /x402/company-deGerman commercial register record. Not offered on Solana: pay on Base or Polygon

POST /x402/domainDomain intelligence and phishing-risk signals

POST /x402/networkHolder of an AS number or IP address

POST /x402/sanctionsSanctions screening

POST /x402/vatEU VAT number validation

The same routes answer under `/mpp/` too, and are MCP tools of the same names.

## What every answer carries

`source`, `source_url` and `retrieved_at`: where the data comes from and when it was read.

`note`: verify at source; not legal, compliance or credit advice. Results are public register data, are not authoritative and can be out of date.

Results are cached for a few hours, so `retrieved_at` can be earlier than the call. The stored copy of a delivered result is deleted after 24 hours.

## Free preview and verification

`POST /v1/preview/<route>` (or `GET` with the fields as query parameters, or the MCP tool `preview`): whether the request can be answered, up to three matching companies, whether a VAT number's format is valid, whether a domain resolves and has mail servers, and the price. It never calls VIES. Limited per client.

`POST /v1/verify` (or the MCP tool `verify`): checks the signature and content hash of a record.

`GET /v1/sources`: every source with its licence, attribution, rate limit and last successful read, and the sanctions list versions.

`GET /.well-known/agosint-keys.json`: the public signing keys. `GET /schemas/<route>.json`: a JSON Schema per record type.

## Receipts

Every record has a `receipt`: `alg` (Ed25519), `kid`, `issued_at`, `content_sha256` and `signature` (base64url, no padding). The canonical form is RFC 8785 (JCS). `content_sha256` is the SHA-256 of JCS(record without `receipt`); the signature covers JCS(record whose `receipt` lacks `signature`).

`pip install rfc8785 cryptography
body = rfc8785.dumps({k: v for k, v in rec.items() if k not in {'receipt'}})
assert hashlib.sha256(body).hexdigest() == rec['receipt']['content_sha256']
sig = b64url_decode(rec['receipt'].pop('signature'))
Ed25519PublicKey.from_public_bytes(b64url_decode(key)).verify(sig, rfc8785.dumps(rec))`

A cached answer keeps the original `retrieved_at`; `issued_at` is the time of the delivery. Within schema version 1, changes only add fields.

## Company

`POST /x402/company` with `{"country":"CZ","id":"45274649"}`, `{"country":"NO","name":"Equinor"}` or `{"lei":"W38RGI023J3WT1HWRP32"}`. Send exactly one of `id`, `name` or `lei`. `country` is a two-letter code and is required with `id` or `name`.

CountryRegisterNotes

CZARES, Czech Ministry of Financeid is the ICO; officers from the commercial register

NOBronnoysund Register Centreid is the organisation number; current roles

GBCompanies HouseOffered only while the operator has configured it; otherwise the quote says not available

USSEC EDGARid is a ticker or a CIK; filings and key facts from the company's reports

otherGLEIF Global LEI Indexby LEI, registration number or exact legal name; ownership chain where reported

A record has `source`, `source_url`, `retrieved_at`, `country`, `id`, `name`, `legal_form`, `status`, `address`, `incorporation_date`, `activity_codes`, `officers` and `raw_fields`, plus `lei`, `parents`, `tickers`, `recent_filings` and `key_facts` where the source has them.

A name that matches several companies returns `ambiguous: true` and up to five `candidates` with their ids, at the normal price. Call again with an id.

## German register

`POST /x402/company-de` with `{"name":"Siemens Aktiengesellschaft","register_type":"HRB","limit":1}`. `name` is required. Optional: `match` (`all`, `any`, `exact`), `register_type`, `register_number`, `register_court`, `legal_form`, `city`, `postal_code`, `include_deleted`, `limit` (1 to 5, default 1; the quote scales with it).

The source is the Handelsregister, the German commercial register portal. Each record is the public register entry as published, with the normalised fields first and everything the register lists under `raw_fields`: register court, number and type, status, legal form, seat, address, officers with their roles and the other details the register publishes about them (such as date of birth and town of residence), representation rules and name history.

It takes up to about a minute and a half. It is not offered on Solana: pay on Base or Polygon.

## Domain

`POST /x402/domain` with `{"domain":"example.com"}`. A public domain name: no URL, port, IP address or local name. An internationalised name is converted to punycode.

`rdap`: registrar, registration, expiry and last-change dates, statuses, name servers, DNSSEC and the entities as the registry publishes them. Registries often redact contact details.

`dns`: A, AAAA, MX, NS, TXT and CAA records from one public resolver.

`mail_security`: SPF, DMARC and MTA-STS records parsed, and a guess of the mail provider from the MX hosts and SPF includes.

`tls`: one TLS handshake with the apex: certificate subject, issuer, validity, names and whether the chain verifies.

No port scan and no subdomain enumeration. To name the company behind the site, the home page and up to four legal-notice pages of the site are read (robots.txt honoured). A name that is not registered and has no records is not charged.

## Network

`POST /x402/network` with `{"asn":"AS3333"}` or `{"ip":"193.0.0.1"}`. Public addresses and allocated AS numbers only.

The answer has the holder, whether the resource is announced, the prefix and origin ASes of an address, its country, the announced prefixes of an AS number, the abuse contact, the allocation block and a route-origin (RPKI) check.

## Due diligence

`POST /x402/due-diligence` with one mode: `{"name":"...","country":"CZ"}`, `{"country":"CZ","id":"45274649"}`, `{"lei":"..."}`, `{"vat":"CZ45274649"}` or `{"domain":"example.com"}`. Optional `include` is a subset of `registry`, `lei`, `vat`, `sanctions`, `domain`.

The record has `entity` (identifiers and how it was matched), `registry`, `lei` with parents, `vat`, `sanctions` (the company, its former names, parents and listed officers, hits and the publication date of each list), `domain`, `checks` (`pass`, `warn`, `fail` or `unknown`, each with its source), `summary.level` (`flags`, `review` or `no_flags`), `sources` and `receipt`. A section that could not be produced says `unavailable` and is listed in `summary.unavailable`.

Not charged when no entity is found or the register of a covered country did not answer. It takes up to about 25 seconds and is not offered on Solana.

## VAT

`POST /x402/vat` with `{"vat":"CZ45274649","requester_vat":"...","expect_name":"..."}`. The answer says whether the number is valid, the registered name and address, whether `expect_name` matches and, with `requester_vat`, the consultation number to keep as audit evidence.

Each check is made for you at the moment of the call and is not stored for other callers. National VAT databases are authoritative. An invalid number, or a member state that is busy, is not charged.

## Sanctions

`POST /x402/sanctions` with `{"name":"...","kind":"entity"}` (optional `country`, `birth_date`, `threshold`, `lists`) or `{"wallet":"0x..."}`. Lists: OFAC SDN, EU consolidated and UK Sanctions List, with each list's publication date in the answer. The UN Security Council list is not included unless the operator switches it on.

A screening aid, not a compliance determination. A clean screen is charged; the route is unavailable when a list is older than a week.

## Guardrails

Public data only. Nothing is looked up that was not asked for, and results are never combined into profiles of people.

The terms at `/terms` list the prohibited uses: stalking, harassment, doxxing, identity fraud, credit, employment, tenancy or insurance decisions, sanctions evasion and anything about minors.

Removal on request: write to agosint@shveik.dev with the register id or exact name. A matching record is replaced by a `removed on request` notice, and is not charged. See `/privacy`.

Requests are limited per route, and each source is called at a polite rate. Queried names are not logged.

## Failures and refunds

A lookup that finds nothing answers 502 `not_fetched` and is not charged and not settled.

A source that is down or too slow answers 502 or 503 and is not charged.

A route or country that is not available answers `not_available` before the quote is signed, and a request for a record removed on request is answered exactly like a value that is not found (502 `not_fetched`, nothing charged).

On the German register route, fewer records than `limit` are charged for the records returned; the rest of the quote is refunded.

## MCP

The MCP server is at `https://agosint.shveik.dev/mcp`, with one tool per route. A tool takes the same JSON as its route and pays with x402 inside the tool call.

Listing the tools and getting quotes works in any MCP client. Paying needs a client that can sign x402 payments.

## Reliability and limits

There is no uptime SLA or uptime guarantee. Service and upstream availability are best-effort and can change.

A quote is shown before payment, and work starts only after settlement. A request refused before settlement is not charged; product-specific refund rules for partial results, orders and deals are described below.

Sources are third-party registers and services that can be slow, rate-limited or down; a lookup a source cannot answer is not charged. The German register route can take up to about 90 seconds.

Free GET docs, guides, pricing and discovery pages are limited to 120 requests per client IP per minute. They return RateLimit headers; a limit response is HTTP 429 with Retry-After. GET /health is a liveness check, not an uptime promise.

Failures are signalled with HTTP 402 when payment is required, 429 when a request is limited, 502 when a result cannot be delivered, and 503 when the service cannot accept work. Follow Retry-After when present. Report problems on the contact page at /contact.

## How it differs

Business-data platforms organize access around accounts and bulk plans; agosint quotes each lookup for stablecoin payment and returns official register data with its source.

## Discovery

`/agents.md`: the guide for agents (preferred; `/llms.txt` is the same text)

`/openapi.json`: request schemas and the payment information (OpenAPI 3.1)

`/.well-known/x402`: the x402 manifest

`/pricing.md`: generated endpoint prices and quote behavior

`/docs`: this API reference

`/mcp`: the MCP server

`/terms` and `/privacy`: terms of use and privacy notice

`/health`: the service status

Try the service without paying: send a GET request to a listed endpoint to receive its free `402` quote, then decide whether to sign and pay. The quote request does not start a paid delivery.

The free `GET /ask?query=...` route searches the product reference. When available, `POST /mcp/docs` is a free, read-only documentation server with search, section lookup, and endpoint schema tools.

[Agent kit on GitHub](https://github.com/shveik-dev/agent-kit) · [Agent guide](/agents.md) · [OpenAPI](/openapi.json) · [x402 manifest](/.well-known/x402)

## API versioning and deprecation policy

Paid routes are the documented `/x402/<name>` and `/mpp/<name>` forms. Consult `/openapi.json` and this reference for the current contract. We aim to preserve compatible behavior.

For breaking changes to a stable API surface, we will announce the change in the documentation and provide `Deprecation` and `Sunset` response headers where applicable, with at least 90 days' notice before removal. Source-dependent behavior can change sooner.

## Authentication and payment

No API key, account, or subscription is required. Payment credentials authorize a specific quoted call and replace a reusable API key. Supported protocols on this service: x402 on Base and Polygon (plus Solana on most routes) or MPP on Base.

For x402, send a valid request without payment and read the HTTP 402 `PAYMENT-REQUIRED` challenge. Sign the offered amount and network, then retry the same request with `PAYMENT-SIGNATURE`. For MPP, the unpaid response includes `WWW-Authenticate: Payment`; retry with the matching `Authorization: Payment` credential. Never authorize a quote you have not checked.

A paid request delivers data only after settlement succeeds. The protocols accept their corresponding payment credential; use the route family's documented path and the exact body used to obtain the quote.

See the [API deprecation policy](/deprecation-policy) for route lifecycle commitments.

## Request examples

due-diligence
First send this valid request without payment. The response is HTTP 402 with the current quote. Review and sign that quote, then retry the same request and body at the MPP path with `Authorization: Payment`, or retry the x402 path with `PAYMENT-SIGNATURE`.

`curl -i -X POST 'https://agosint.shveik.dev/x402/due-diligence' -H 'content-type: application/json' --data-binary @- <<'JSON'
{"country":"CZ","name":"ČEZ"}
JSON`

Paid retry paths: `https://agosint.shveik.dev/x402/due-diligence` (x402) or `https://agosint.shveik.dev/mpp/due-diligence` (MPP), with the same JSON body and matching `PAYMENT-SIGNATURE` or `Authorization: Payment` credential.
company
First send this valid request without payment. The response is HTTP 402 with the current quote. Review and sign that quote, then retry the same request and body at the MPP path with `Authorization: Payment`, or retry the x402 path with `PAYMENT-SIGNATURE`.

`curl -i -X POST 'https://agosint.shveik.dev/x402/company' -H 'content-type: application/json' --data-binary @- <<'JSON'
{"country":"CZ","id":"45274649"}
JSON`

Paid retry paths: `https://agosint.shveik.dev/x402/company` (x402) or `https://agosint.shveik.dev/mpp/company` (MPP), with the same JSON body and matching `PAYMENT-SIGNATURE` or `Authorization: Payment` credential.
company-de
First send this valid request without payment. The response is HTTP 402 with the current quote. Review and sign that quote, then retry the same request and body at the MPP path with `Authorization: Payment`, or retry the x402 path with `PAYMENT-SIGNATURE`.

`curl -i -X POST 'https://agosint.shveik.dev/x402/company-de' -H 'content-type: application/json' --data-binary @- <<'JSON'
{"limit":1,"name":"Siemens Aktiengesellschaft","register_type":"HRB"}
JSON`

Paid retry paths: `https://agosint.shveik.dev/x402/company-de` (x402) or `https://agosint.shveik.dev/mpp/company-de` (MPP), with the same JSON body and matching `PAYMENT-SIGNATURE` or `Authorization: Payment` credential.
domain
First send this valid request without payment. The response is HTTP 402 with the current quote. Review and sign that quote, then retry the same request and body at the MPP path with `Authorization: Payment`, or retry the x402 path with `PAYMENT-SIGNATURE`.

`curl -i -X POST 'https://agosint.shveik.dev/x402/domain' -H 'content-type: application/json' --data-binary @- <<'JSON'
{"domain":"example.com"}
JSON`

Paid retry paths: `https://agosint.shveik.dev/x402/domain` (x402) or `https://agosint.shveik.dev/mpp/domain` (MPP), with the same JSON body and matching `PAYMENT-SIGNATURE` or `Authorization: Payment` credential.
network
First send this valid request without payment. The response is HTTP 402 with the current quote. Review and sign that quote, then retry the same request and body at the MPP path with `Authorization: Payment`, or retry the x402 path with `PAYMENT-SIGNATURE`.

`curl -i -X POST 'https://agosint.shveik.dev/x402/network' -H 'content-type: application/json' --data-binary @- <<'JSON'
{"asn":"AS3333"}
JSON`

Paid retry paths: `https://agosint.shveik.dev/x402/network` (x402) or `https://agosint.shveik.dev/mpp/network` (MPP), with the same JSON body and matching `PAYMENT-SIGNATURE` or `Authorization: Payment` credential.
sanctions
First send this valid request without payment. The response is HTTP 402 with the current quote. Review and sign that quote, then retry the same request and body at the MPP path with `Authorization: Payment`, or retry the x402 path with `PAYMENT-SIGNATURE`.

`curl -i -X POST 'https://agosint.shveik.dev/x402/sanctions' -H 'content-type: application/json' --data-binary @- <<'JSON'
{"kind":"entity","name":"Aerocaribbean Airlines"}
JSON`

Paid retry paths: `https://agosint.shveik.dev/x402/sanctions` (x402) or `https://agosint.shveik.dev/mpp/sanctions` (MPP), with the same JSON body and matching `PAYMENT-SIGNATURE` or `Authorization: Payment` credential.
vat
First send this valid request without payment. The response is HTTP 402 with the current quote. Review and sign that quote, then retry the same request and body at the MPP path with `Authorization: Payment`, or retry the x402 path with `PAYMENT-SIGNATURE`.

`curl -i -X POST 'https://agosint.shveik.dev/x402/vat' -H 'content-type: application/json' --data-binary @- <<'JSON'
{"expect_name":"ČEZ","vat":"CZ45274649"}
JSON`

Paid retry paths: `https://agosint.shveik.dev/x402/vat` (x402) or `https://agosint.shveik.dev/mpp/vat` (MPP), with the same JSON body and matching `PAYMENT-SIGNATURE` or `Authorization: Payment` credential.

## Command-line tool

A small shell script (needs only sh and curl) lists the endpoints, prints the quote of a call and sends a call you have already signed. It never holds keys and never signs a payment.

`curl -fsSL https://agosint.shveik.dev/install.sh | sh
agosint help
agosint endpoints`

Commands: help, endpoints, docs, pricing, openapi, quote, call, health, version, update. Exit code 3 means a payment is required and the quote was printed. The installer puts the script in ~/.local/bin; its source is at /cli.