# 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? Start with the free MCP demo

28 of the JSON-data tools below (everything except PDF/QR generation) are
also available through MCP (Streamable HTTP transport, no payment) with 30
free tool calls per UTC day per anonymous client — 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 production automation, higher volume and the binary endpoints (PDF, QR), use the x402 HTTP API below.

That command is for Claude Code. Client-specific instructions: https://toolrail.dev/integrate
Browser demo (no wallet): https://toolrail.dev/try or https://toolrail.dev/probar
Downloadable x402 buyer example: https://toolrail.dev/assets/examples/x402-buyer.mjs
Example setup and price limit: https://toolrail.dev/assets/examples/README.md

## 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 supported 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 LATAM exchange rates with their individual dates and sources (/latam/fx), Argentina's official/market gap, Colombia's TRM, Peru's SBS rate and Mexico's FIX; check partial errors and stale values
- 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. Use when an agent must hand a person a document: invoices, quotes, reports or contracts as a PDF file.
```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.002
Current VAT rates for supported European countries (EU-27 + UK, CH, NO...). Standard, reduced and super-reduced rates, provided through the third-party vatnode dataset; verify applicability for your transaction. Use when pricing, invoicing or checking tax for a customer in Europe and you need that country's VAT rate.
```bash
curl "https://toolrail.dev/vat/rates?country=DE"
```

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

### POST /vat/price — $0.002
VAT price calculator for supported European countries: net-to-gross or gross-to-net with the current standard or reduced rate. Returns net, VAT amount and gross. Use when you have a price and a European country and need the amount with or without VAT.
```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. Use when converting an amount between major currencies at an official reference rate, today or on a past date.
```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. Use when you need many exchange rates at once against one base currency, today or historically.
```bash
curl "https://toolrail.dev/fx/rates?base=USD"
```

### GET /days/holidays — $0.003
Official public holidays for supported countries (any year 1975-2075): date, local and English name, nationwide vs regional flag. Chile enhanced with a curated statutory table. Use when checking whether a date is a public holiday in a country or listing a year's holidays.
```bash
curl "https://toolrail.dev/days/holidays?country=DE&year=2026"
```

### GET /days/business-days — $0.003
Business-day calculator for supported countries: add N working days to a date skipping weekends and official public holidays. Essential for scheduling, deadlines and logistics. Use when computing a deadline, delivery or payment date that must skip weekends and public holidays.
```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. Use when someone enters a bank account (IBAN) and you must catch typos before a transfer.
```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. Use when normalizing or checking phone numbers before saving a contact or sending SMS or WhatsApp.
```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.002
Validate the format and supported check-digit rules of tax IDs across Latin America and Spain: Chile RUT, Argentina CUIT/CUIL, Brazil CPF/CNPJ, Mexico RFC, Peru RUC, Colombia NIT, Spain NIF/NIE. Does not verify identity or registration with a tax authority. Use when checking a Latin American or Spanish tax ID's format before saving a customer or an invoice.
```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.005
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. Use when a contract, rent or loan is expressed in UF, UVA, UVR or UDI and you need its value in local currency.
```bash
curl "https://toolrail.dev/latam/indexacion?unidad=uva&monto=100"
```

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

### GET /latam/fx — $0.015
LATAM exchange rates against USD in one call: CLP, ARS oficial+blue with gap, BRL PTAX, MXN FIX, COP TRM and PEN SBS. Returns source and observation information per currency; Argentine blue is a market quote, not an official central-bank rate. Partial results are identified. Use when you need official central-bank exchange rates for several Latin American currencies against the US dollar in a single call.
```bash
curl "https://toolrail.dev/latam/fx"
```

### GET /latam/iva — $0.002
VAT (IVA) rates for 17 Latin American countries, including Argentina, Chile, Colombia, Mexico, Peru (IGV) and the Dominican Republic (ITBIS): standard and reduced rates, plus net-to-gross or gross-to-net calculation. Reviewed dataset with source and review date; Brazil is excluded because it has no single rate. Use when pricing, quoting or invoicing in Latin America and you need the local VAT rate or the amount with or without tax.
```bash
curl "https://toolrail.dev/latam/iva?pais=CL&monto=100000&direccion=neto-a-bruto"
```

### GET /latam/unidades-tributarias — $0.003
Annual tax units used to express fines, thresholds and fees in Latin America: UIT (Peru), UVT (Colombia) and UMA (Mexico). Official value for a date with its legal act and validity window, plus conversion of N units to local currency. Use when a law, fine, tax threshold or fee is stated in UIT, UVT or UMA and you need the amount in local currency.
```bash
curl "https://toolrail.dev/latam/unidades-tributarias?unidad=uvt&cantidad=10"
```

### GET /br/indices — $0.005
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. Use when you need Brazil's interest rate (SELIC/CDI), inflation (IPCA) or official dollar (PTAX).
```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. Use when you have a Brazilian postal code (CEP) and need the full address.
```bash
curl "https://toolrail.dev/br/cep?cep=01310-100"
```

### GET /ar/indices — $0.005
Argentina's macro pulse: latest monthly inflation, compounded year-over-year inflation, and country risk (riesgo país) in basis points. Use when you need Argentina's latest inflation or country risk for a report or a price adjustment.
```bash
curl "https://toolrail.dev/ar/indices"
```

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

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

### GET /mx/indicadores — $0.005
Mexico's official FIX dollar rate (used for obligations) and TIIE 28-day interest rate, from Banco de México. Use when you need Mexico's official FIX dollar rate or the TIIE interest rate.
```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. Use when adjusting a Chilean rent, debt or alimony amount for inflation (IPC) between two months.
```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. Use when you need a scannable QR image for a URL, payment link or label.
```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.005
Chilean economic indicators: UF, UTM, dolar observado, euro, IPC — current or for a given date. Official Banco Central de Chile data. Use when you need the UF, UTM, dollar or euro value in Chile for today or a past date.
```bash
curl "https://toolrail.dev/cl/indicadores?indicador=uf"
```

### GET /cl/uf — $0.005
Convert amounts between UF (Unidad de Fomento) and Chilean pesos at any date. Essential for Chilean contracts, rents and insurance. Use when an amount is expressed in UF and you need Chilean pesos, or the reverse.
```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. Use when computing a legal or administrative deadline in Chile in business days (días hábiles).
```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. Use when you need Chile's official holiday calendar (feriados) for scheduling.
```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). Use when a Chilean RUT is entered in a form or file and you must catch typos before saving.
```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. Use when estimating a Chilean employee's take-home (líquido) pay from a gross salary.
```bash
curl -X POST https://toolrail.dev/cl/sueldo-liquido -H "Content-Type: application/json" -d '{"bruto":1500000,"afp":"modelo"}'
```

### 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. Use when you want a practical guide to building and selling your own paid API with x402.
```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` — MCP demo (30 free tool calls/day/client; 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.