# Toolrail — agent skill

Toolrail is a pay-per-call utility API for AI agents. Payment uses the x402 protocol:
an unpaid request returns HTTP 402 with machine-readable payment requirements in the
`PAYMENT-REQUIRED` header (base64 JSON) — every 402 offers TWO payment options
(USDC on Base mainnet and USDC on Solana mainnet); pay either one with any x402
client, retry with the payment proof, and receive the resource. Gas is sponsored
by the facilitator — the paying wallet only needs USDC.

Base URL: https://toolrail.dev

## No wallet? Use MCP instead (free, rate-limited)

27 of the JSON-data tools below (everything except PDF/QR generation) are
also available for free over MCP (Streamable HTTP transport, no payment, subject to
the same per-IP rate limit as the rest of the site) — the lower-friction option for
Claude Code, Claude Desktop, Cursor, or any MCP-compatible client:

```
claude mcp add --transport http toolrail https://toolrail.dev/mcp
```

For unlimited access and the binary endpoints (PDF, QR), use the x402 HTTP API below.

## Triggers

Use this skill when the user (or your task) needs to:

- Generate a PDF document: invoice, report, contract, or any HTML rendered to PDF
- Know public holidays or add business days to a date in any of 187 countries
- Get EU VAT rates, validate an EU VAT number, or compute net/gross prices with VAT
- Convert currencies or fetch official ECB exchange rates (current or historical)
- Validate or format an IBAN or a phone number from any country
- Generate a QR code image
- Get official LATAM exchange rates: all six major currencies vs USD in one call (/latam/fx), Argentina's blue-dollar gap, Colombia's legal TRM, Peru's SBS rate, Mexico's FIX
- Query LATAM macro data: Brazil's SELIC/CDI/IPCA, Argentina's inflation and country risk, inflation-indexed units (UF, UVA, UVR, UDI)
- Validate a tax ID from Chile, Argentina, Brazil, Mexico, Peru, Colombia or Spain; look up a Brazilian postal code (CEP)
- Adjust a Chilean amount by official IPC inflation between two months (reajuste)
- Work with Chilean data: UF/UTM values, UF-CLP conversion, business days with Chilean holidays, RUT validation, net salary ("sueldo liquido") calculation, on-duty pharmacies

## How to call (with an x402 client)

1. Install an x402-capable HTTP client (e.g. the official x402 SDKs: https://docs.x402.org).
2. Configure it with a wallet holding USDC on Base OR on Solana — both networks are accepted on every endpoint; the client picks whichever it supports.
3. Call any endpoint below; the client handles the 402 -> pay -> retry loop automatically.

Without a client, you can still inspect: `curl https://toolrail.dev/fx/convert?from=USD&to=EUR&amount=100 -i`
returns the 402 challenge so you can see exactly what payment is required.

## Endpoints

### POST /pdf — $0.01
Generate a print-ready PDF from JSON data (invoice, report, contract templates) or raw HTML. Returns application/pdf. No account or subscription needed.
```bash
curl -X POST https://toolrail.dev/pdf -H "Content-Type: application/json" -d '{"template":"invoice","data":{"number":"F-001","currency":"USD","tax_rate":19,"issuer":{"name":"Acme"},"client":{"name":"Client Inc"},"items":[{"description":"Consulting","quantity":2,"unit_price":150}]}}' -o invoice.pdf
```

### GET /vat/rates — $0.003
Current VAT rates for 44 European countries (EU-27 + UK, CH, NO...). Standard, reduced and super-reduced rates, sourced daily from the European Commission TEDB.
```bash
curl "https://toolrail.dev/vat/rates?country=DE"
```

### POST /vat/validate — $0.005
Validate an EU VAT number against the official European Commission VIES registry, with retries and caching for reliability. Returns validity, company name and address.
```bash
curl -X POST https://toolrail.dev/vat/validate -H "Content-Type: application/json" -d '{"countryCode":"IE","vatNumber":"6388047V"}'
```

### POST /vat/price — $0.003
VAT price calculator for 44 European countries: net-to-gross or gross-to-net with the current standard or reduced rate. Returns net, VAT amount and gross.
```bash
curl -X POST https://toolrail.dev/vat/price -H "Content-Type: application/json" -d '{"amount":100,"country":"DE","direction":"net-to-gross"}'
```

### GET /fx/convert — $0.003
Convert between 30+ major currencies using official European Central Bank reference rates, current or historical since 1999.
```bash
curl "https://toolrail.dev/fx/convert?from=USD&to=EUR&amount=100"
```

### GET /fx/rates — $0.003
Full ECB reference rate table for any base currency, current or for a historical date since 1999.
```bash
curl "https://toolrail.dev/fx/rates?base=USD"
```

### GET /days/holidays — $0.003
Official public holidays for 187 countries (any year 1975-2075): date, local and English name, nationwide vs regional flag. Chile enhanced with a curated statutory table.
```bash
curl "https://toolrail.dev/days/holidays?country=DE&year=2026"
```

### GET /days/business-days — $0.003
Business-day calculator for 187 countries: add N working days to a date skipping weekends and official public holidays. Essential for scheduling, deadlines and logistics.
```bash
curl "https://toolrail.dev/days/business-days?country=US&from=2026-08-01&days=10"
```

### POST /validate/iban — $0.002
Validate an IBAN (international bank account number): ISO 13616 mod-97 check digits and per-country length registry for 88 countries. Returns formatted IBAN and BBAN.
```bash
curl -X POST https://toolrail.dev/validate/iban -H "Content-Type: application/json" -d '{"iban":"DE89 3704 0044 0532 0130 00"}'
```

### POST /validate/phone — $0.002
Validate and format phone numbers for ~240 regions (Google libphonenumber): validity, region, line type, E.164 / international / national formats.
```bash
curl -X POST https://toolrail.dev/validate/phone -H "Content-Type: application/json" -d '{"phone":"+56 9 6123 4567"}'
```

### POST /validate/tax-id — $0.003
Validate tax IDs across Latin America and Spain with official check-digit algorithms: Chile RUT, Argentina CUIT/CUIL, Brazil CPF and CNPJ, Mexico RFC, Peru RUC, Colombia NIT, Spain NIF/NIE. The only pan-LATAM ID validator for agents.
```bash
curl -X POST https://toolrail.dev/validate/tax-id -H "Content-Type: application/json" -d '{"country":"BR","id":"529.982.247-25"}'
```

### GET /latam/indexacion — $0.003
Latin American inflation-indexed units used in real contracts, mortgages and rents: UF (Chile), UVA (Argentina), UVR (Colombia), UDI (Mexico) — live official central-bank values with local-currency conversion.
```bash
curl "https://toolrail.dev/latam/indexacion?unidad=uva&monto=100"
```

### GET /latam/dolar-argentina — $0.003
Argentine dollar quotes in one call: oficial, blue (parallel) and euro rates plus the gap percentage — the region's most watched FX spread.
```bash
curl "https://toolrail.dev/latam/dolar-argentina"
```

### GET /latam/fx — $0.01
All official LATAM exchange rates against USD in ONE call: Chilean peso (central bank), Argentine oficial+blue with gap, Brazilian real (PTAX), Mexican peso (FIX), Colombian peso (legal TRM) and Peruvian sol (SBS). The region's FX aggregator no one else serves.
```bash
curl "https://toolrail.dev/latam/fx"
```

### GET /br/indices — $0.003
Brazil's key official rates in one call: SELIC target, annualized CDI, monthly IPCA inflation and PTAX dollar — straight from Banco Central do Brasil's SGS API.
```bash
curl "https://toolrail.dev/br/indices"
```

### GET /br/cep — $0.002
Brazilian postal code (CEP) lookup: street, neighborhood, city, state and IBGE code for any of Brazil's 700k+ CEPs.
```bash
curl "https://toolrail.dev/br/cep?cep=01310-100"
```

### GET /ar/indices — $0.003
Argentina's macro pulse: latest monthly inflation, compounded year-over-year inflation, and country risk (riesgo país) in basis points.
```bash
curl "https://toolrail.dev/ar/indices"
```

### GET /co/trm — $0.003
Colombia's official TRM (Tasa Representativa del Mercado) — the legal COP/USD rate used for taxes and contracts, with validity dates.
```bash
curl "https://toolrail.dev/co/trm"
```

### GET /pe/tipo-cambio — $0.003
Peru's official SBS exchange rate (buy/sell PEN per USD) from the central bank (BCRP).
```bash
curl "https://toolrail.dev/pe/tipo-cambio"
```

### GET /mx/indicadores — $0.003
Mexico's official FIX dollar rate (used for obligations) and TIIE 28-day interest rate, from Banco de México.
```bash
curl "https://toolrail.dev/mx/indicadores"
```

### GET /cl/reajuste — $0.01
Chilean IPC adjustment calculator: compound official monthly inflation between two months to reajust any amount — the standard calculation for rents, alimony and contracts in Chile.
```bash
curl "https://toolrail.dev/cl/reajuste?desde=2025-01&hasta=2025-06&monto=500000"
```

### POST /qr — $0.002
Generate a QR code as PNG or SVG from any text or URL (up to 2000 chars, 64-2048 px). Pairs with the PDF endpoint for payment links and labels.
```bash
curl -X POST https://toolrail.dev/qr -H "Content-Type: application/json" -d '{"data":"https://toolrail.dev","format":"png","size":512}' -o qr.png
```

### GET /cl/indicadores — $0.003
Chilean economic indicators: UF, UTM, dolar observado, euro, IPC — current or for a given date. Official Banco Central de Chile data.
```bash
curl "https://toolrail.dev/cl/indicadores?indicador=uf"
```

### GET /cl/uf — $0.003
Convert amounts between UF (Unidad de Fomento) and Chilean pesos at any date. Essential for Chilean contracts, rents and insurance.
```bash
curl "https://toolrail.dev/cl/uf?monto=50&direccion=uf-clp"
```

### GET /cl/dias-habiles — $0.003
Chilean business-day calculator: add N working days to a date respecting national holidays. Types: administrativo (Mon-Fri) or corrido.
```bash
curl "https://toolrail.dev/cl/dias-habiles?desde=2026-08-01&plazo=10"
```

### GET /cl/feriados — $0.003
Official Chilean public holidays for 2026-2027 as structured JSON, including statutory moved holidays.
```bash
curl "https://toolrail.dev/cl/feriados?ano=2026"
```

### POST /cl/rut — $0.002
Validate and format a Chilean RUT (tax ID) including check digit (modulo 11).
```bash
curl -X POST https://toolrail.dev/cl/rut -H "Content-Type: application/json" -d '{"rut":"12.345.678-5"}'
```

### POST /cl/sueldo-liquido — $0.01
Chilean net salary calculator: gross to net with AFP, health, unemployment insurance and impuesto unico using live UF/UTM values and current legal brackets.
```bash
curl -X POST https://toolrail.dev/cl/sueldo-liquido -H "Content-Type: application/json" -d '{"bruto":1500000,"afp":"modelo"}'
```

### GET /cl/farmacias-turno — $0.003
On-duty (night shift) pharmacies in Chile by comuna, from the official MINSAL registry.
```bash
curl "https://toolrail.dev/cl/farmacias-turno?comuna=VALPARAISO"
```

### GET /guia/pdf — $7.00
PDF edition of 'Build your own x402 API' — available in Spanish, English or Portuguese (?lang=es|en|pt). A real-world walkthrough of building Toolrail: architecture, real bugs found and fixed, security checklist, discovery channels, and an honest revenue simulation. Includes a printable launch checklist. One-time purchase.
```bash
curl "https://toolrail.dev/guia/pdf?lang=en" -o guide-x402.pdf
```

## Free endpoints

- `GET /` — JSON catalog of all endpoints with prices
- `GET /health` — liveness probe
- `GET /pdf/templates` — full JSON schemas + examples for the PDF templates
- `GET /openapi.json` — OpenAPI 3.1 spec
- `POST /mcp` — free MCP server (see above)
- `GET /llms.txt` — plain-text service summary

## Notes for agents

- Responses are JSON except `POST /pdf` (application/pdf bytes) and `POST /qr` (image/png or image/svg+xml).
- Chilean money endpoints (`/cl/*`) use live official UF/UTM values; results include the source and value date.
- Calculations (VAT, net salary) are informative and not legal/tax advice.