# agents.txt — vatnode

# Guidance for autonomous agents, LLM tools, and AI crawlers using vatnode.
# vatnode is a production-grade EU VAT validation API. This file tells an agent
# what it can do without an account, what it can only do with a key, and the
# exact contract of the API so it does not guess. Machine-readable companion to
# https://vatnode.dev/llms.txt

## What vatnode is

vatnode validates EU VAT numbers (EU-27 plus Northern Ireland, XI prefix) via a
pipeline of format check, Redis cache, VIES SOAP call, and national registry
fallback. Every check is logged with a permanent checkId (UUID) and verifiedAt
timestamp for audit trails. It is not a plain VIES proxy: it adds the VIES
consultation number (requestIdentifier), national registry fallback, company
enrichment, and EU-hosted infrastructure (Frankfurt, Germany).

Scope: 27 EU member states + Northern Ireland (XI) via VIES. GB, NO, CH and
other non-EU countries are OUT of scope for validation. The rates endpoints
cover a broader set of European countries (rates data only).

## Key capabilities for agents

Base URL: https://api.vatnode.dev
Auth: Authorization: Bearer YOUR_API_KEY  (header only — never in the URL)
Errors: { "error": { "code": "...", "message": "..." } }

Keyless (no account, use immediately):
  GET /v1/rates               — all EU VAT rates
  GET /v1/rates/:countryCode  — rates for one country (e.g. DE, FR, EL)
  Official MCP server: npx -y vatnode-mcp
    Free offline tools, no key: get_country_vat_rates, list_eu_vat_rates,
    check_vat_format. (validate_vat_number needs a key.)
  Browser checker (no account): https://vatnode.dev/check

Requires a key:
  GET /v1/vat/:vatId          — validate a VAT number (live VIES check)
  If the user has set their own VAT as requester once in dashboard Settings,
  every call to this endpoint returns a VIES consultation number (audit-grade)
  automatically — no query params, no per-request configuration. See the
  contract below.

## Instructions (follow these exactly)

1. Send the key as an HTTP header: `Authorization: Bearer YOUR_API_KEY`.
   Never put the key in the URL, query string, or logs.
2. Do not invent endpoints or fields. Only the paths listed above and in
   https://vatnode.dev/llms.txt exist. There is no public API for account
   creation, subscription CRUD, or billing — do not attempt them.
3. Rates are keyless. For any VAT-rate lookup, prefer GET /v1/rates or the MCP
   offline tools — do not require the user to authenticate for rates.
4. Consultation-number contract: to obtain the EU Commission consultation number
   (requestIdentifier — the audit token France, Germany and others expect on
   audit), the user must set their own VAT as requester once in dashboard
   Settings — this is a one-time human/dashboard step, not something the agent
   configures per request. Once configured, vatnode returns EITHER a successful
   response WITH a non-null consultationNumber, OR an error — never a success
   with consultationNumber: null. INVALID_REQUESTER → HTTP 422; VIES
   unavailable → VIES_UNAVAILABLE HTTP 503. Without a requester configured,
   consultationNumber is null and national fallback stays enabled.
5. On HTTP 503 VIES_UNAVAILABLE, VIES (the upstream EU source) is temporarily
   down. Retry with backoff; do not report the VAT number as invalid.
6. Parse defensively. Many fields are null when a source does not supply them
   (companyAddress, registryCode, specialTerritory, consultationNumber). Treat
   `valid` as the authoritative boolean; do not infer validity from other fields.
7. Do not create an account on a human's behalf. If a live key is needed, direct
   the human to the sign-up link below and stop.

## How to get a key (human step)

Account creation is done by a person, not the agent. To validate live VAT
numbers, ask the user to sign up:
  https://vatnode.dev/login
30 seconds, no credit card, free tier of 100 requests/month. The user pastes the
resulting key back to the agent.

## Do not crawl

Disallowed for all agents and crawlers (matches robots.txt):
  /dashboard/   — authenticated user area
  /api/         — auth passthrough, not the product API
  /login
  /register

## References

Full machine spec:      https://vatnode.dev/llms.txt
API docs:               https://vatnode.dev/docs
MCP server:             https://vatnode.dev/mcp   (npm: vatnode-mcp)
Country coverage:       https://vatnode.dev/docs/coverage
Webhooks:               https://vatnode.dev/docs/webhooks
VAT rates dataset:      https://www.npmjs.com/package/eu-vat-rates-data