# Fairverra Agent API

> API-first domain registration for AI agents and provisioning systems. Check
> prices in EUR or USD (pass currency USD on /domains/check), then register,
> transfer, renew, restore, cancel, uncancel and trade domains, manage DNS
> (/dns/{domain}/records), DNSSEC, handles, nameserver glue, and pay from a
> prepaid EUR wallet via an explicit quote -> confirm step. REST, OpenAPI 3.1,
> stable error codes, free self-service sandbox.

Key facts:

- Sandbox base URL: https://sandbox.api.fairverra.com/v1 (free fv_test_ keys, simulated registrar, Mollie test mode)
- Production base URL: https://api.fairverra.com/v1 (fv_live_ keys, self-service:
  signup -> verify -> billing details -> accept terms, privacy and the domain
  registration agreement (GET /me acceptances, POST /me/acceptances; humans
  accept on https://login.fairverra.com/account; texts at /legal, /terms,
  /privacy, /domain-registration-agreement) -> first wallet
  deposit -> POST /keys/upgrade gives the full key; prepaid wallet)
- Auth: Authorization: Bearer <key>
- Keyless trial: POST /domains/check works without a key (strict IP limit, list prices)
- Get a sandbox key without human contact: POST /signup {"email"} returns a
  restricted key immediately (check/pricing/whois); POST /signup/verify
  {"email","code"} swaps it for a full-access key. Humans without an agent
  can use https://fairverra.com/get-started (email + code form) or
  https://fairverra.com/ai (Add to Cursor / Claude / Claude Code).
- Money is {amount, currency} (no *_eur). Confirm debits quote total (settlement, EUR).
  Show presentment to the human; never convert FX yourself. To see dollar prices,
  POST /domains/check {"domain":"...","currency":"USD"} (keyless or with a key) or
  GET /pricing/extensions?currency=USD. prices stay EUR; presentment is the USD
  label. The wallet stays EUR.
- Money only moves on POST /approvals/{id}/confirm of a priced quote (POST /quotes,
  actions: register, transfer, renew, restore, cancel, uncancel, trade).
  cancel/uncancel are EUR 0 Fairverra status only (not a registry delete).
  trade is EUR 0 registrant change; TLD must have trade_supported.
  Failed registrar actions are auto-refunded to the wallet.
- DNS records live at /dns/{domain}/records (not /domains/{id}/dns/records).
  DNSSEC is GET/PUT/DELETE /domains/{id}/dnssec (send DNSKEYs, not DS).
  URL-forward is GET/PUT/DELETE /domains/{id}/url-forward (301 apex+www; not a quote).
  Nameserver groups accept hostnames or {hostname, ip, ip6} for glue.
  Fairverra DNS is nameserver_group dns-fairverra1 (use that name in quotes).
- NL phones need phone.area_code without a leading 0 (6 for mobile) and
  subscriber_number for the rest. PUT /handles/{id} cannot change Individual
  first/last name or Organization company.
- Account language (nl/en, empty=nl) and status_email (on/off, empty=on) are on
  GET /me. PATCH /me to set them. status_email off suppresses renewal and
  transfer mail; login and signup codes still send. API errors stay English.
- Errors are always {"error": "...", "code": "STABLE_CODE"}; codes never change.
- Remote MCP server (streamable HTTP) at https://sandbox.api.fairverra.com/mcp (sandbox) and
  https://api.fairverra.com/mcp (production) — auth: fv_ key as Authorization header,
  or OAuth 2.0 (discovered automatically via RFC 9728; sign in with email +
  one-time code — this is how claude.ai custom connectors work, no API key
  needed). Humans install at https://fairverra.com/ai. Claude Code plugin:
  marketplace gerbenlive/fairverra-claude-plugin, install fairverra@fairverra
  (skills wrap the production MCP). Tools: whoami, check_domain, whois_check,
  list_extension_pricing, get_registration_requirements, list_domains, list_handles,
  create_handle, update_handle, set_domain_handles, get_wallet, create_deposit_link, create_quote, get_approval,
  confirm_approval (requires explicit human approval), accept_legal_documents
  (requires explicit human approval; all three current documents), update_account_preferences,
  update_billing,
  upgrade_key, set_auto_renew, get_auth_code, set_transfer_lock,
  list_nameserver_groups, create_nameserver_group (optional glue ip/ip6 per hostname), set_domain_nameservers,
  list_dns_records, add_dns_record, update_dns_record, delete_dns_record,
  get_dnssec, set_dnssec, disable_dnssec, get_url_forward, set_url_forward,
  disable_url_forward, list_payment_methods,
  create_payment_method_setup_link.
- ChatGPT directory connector (limited, no purchases): https://api.fairverra.com/mcp/chatgpt
  — search, DNS, nameservers and get_domain_page only. Full MCP remains
  https://api.fairverra.com/mcp.

## Docs

- [Agent skill (SKILL.md)](https://fairverra.com/agent-onboarding/SKILL.md): drop-in skill file for Claude/Cursor agents — signup to registered domain
- [Add to Cursor / Claude](https://fairverra.com/ai): one-click MCP install
- [What to tell your assistant](https://fairverra.com/prompts): copy-paste prompts after Fairverra is connected
- [Check if a domain is free](https://fairverra.com/prompts/check-availability): One name, availability, premium flag, register and renew price.
- [Find available names](https://fairverra.com/prompts/find-names): Invent names, then check each one. Fairverra checks one domain per call.
- [Check a list of domains](https://fairverra.com/prompts/bulk-check): Walk a list. One check_domain call per name.
- [Register a domain](https://fairverra.com/prompts/register): TLD rules, handles, then a priced quote. Nothing is charged until you confirm.
- [Set DNS records](https://fairverra.com/prompts/dns-records): A, AAAA, CNAME, TXT, MX you paste. Only when the domain is on dns-fairverra1.
- [Change nameservers](https://fairverra.com/prompts/change-nameservers): Point the domain at another nameserver group. Wrong hosts take DNS and mail offline.
- [Use Fairverra DNS](https://fairverra.com/prompts/use-fairverra-dns): Put the domain on dns-fairverra1 so record tools work.
- [Set mail DNS](https://fairverra.com/prompts/mail-dns): MX, SPF, DKIM, DMARC from values you paste. Fairverra does not create mailboxes.
- [DNSSEC](https://fairverra.com/prompts/dnssec): Show the published DNSKEYs. Do not replace keys unless you paste DNSKEYs, not DS.
- [301-forward a domain](https://fairverra.com/prompts/url-forward): Apex and www to an https URL. Not a quote. Mail MX stays.
- [Domains expiring soon](https://fairverra.com/prompts/expiring-soon): List domains in the next N days and which have auto-renew off.
- [Renew a domain](https://fairverra.com/prompts/renew): Priced renew quote first. Nothing is charged until you confirm.
- [Turn on auto-renew](https://fairverra.com/prompts/auto-renew): No quote now. Later renewals debit the EUR wallet or a saved card.
- [Restore an expired domain](https://fairverra.com/prompts/restore): See if restore is still possible and what it costs, then quote if you want it.
- [Cancel auto-renew / mark for expiry](https://fairverra.com/prompts/cancel): €0 Fairverra status quote. This is not a registry delete.
- [Transfer a domain in](https://fairverra.com/prompts/transfer-in): Transfer quote with auth code. Charged only after you confirm.
- [Transfer a domain away](https://fairverra.com/prompts/transfer-out): Unlock if the TLD allows it, then fetch the auth code. Treat the code as a secret.
- [Change the registrant](https://fairverra.com/prompts/change-owner): A €0 trade quote when the TLD supports it. Not an admin/tech handle swap.
- [Contacts (handles)](https://fairverra.com/prompts/contacts): List or create handles, or swap admin/billing/tech. Registrant change is a trade.
- [Wallet balance and top-up](https://fairverra.com/prompts/wallet): EUR prepaid balance, recent charges, and a deposit link. Money moves after you pay.
- [Update billing details](https://fairverra.com/prompts/billing): Invoice name, address, country (ISO-2). Company filled means business VAT.
- Claude Code plugin:
```
claude plugin marketplace add gerbenlive/fairverra-claude-plugin
claude plugin install fairverra@fairverra
```
  Skills: register-and-connect-domain, transfer-domain, manage-dns. Connector: https://api.fairverra.com/mcp.
- [Quickstart](https://fairverra.com/docs/quickstart): sandbox key to registered domain in five curl commands
- [API overview](https://fairverra.com/docs): endpoint groups, auth, guarantees
- [OpenAPI 3.1 spec](https://sandbox.api.fairverra.com/v1/openapi): the authoritative machine-readable contract

## Sandbox test names

Deterministic magic names on the simulated registrar: sandbox-premium*,
sandbox-taken*, sandbox-requirements*, sandbox-pending* (slow transfer),
sandbox-locked*, sandbox-expiring-<days>* (registers with expiry that many
days out, e.g. sandbox-expiring-30-test.nl expires in 30 days — handy for
testing the renewal window and expiry notices), sandbox-redemption* (registers
already expired, 30 days past — test a restore quote + confirm); auth code
SANDBOX-WRONG; contact last name "sandbox-rejected".