# Namefi API
  > Namefi lets you register traditional domains as NFTs and manage their DNS records via API.
  > MCP server (every operation below as MCP tools): https://api.namefi.io/mcp — discovery descriptor at https://namefi.io/.well-known/mcp/servers.json
  > Full single-file reference (Web3 payments + outbound guides inlined): https://namefi.io/llms-full.txt

## Base URLs
- https://api.namefi.io/v-next/

## Agent policy (mandatory)

When the user wants to search, register, renew, configure, or manage DNS for a Namefi domain:

1. **Prefer MCP.** If your client supports MCP and Namefi is not already connected, install/connect `https://api.namefi.io/mcp` (see "MCP Server" below) **before** searching or registering.
2. **Use MCP tools** for availability search, registration orders, order polling, DNS records, domain config, and outbound lead-finding.
3. **Do not** answer a domain request with curl-only recipes when MCP can be added in this session.
4. **REST/curl is a fallback only** when: your client cannot install MCP, the MCP install failed or is blocked, or the user explicitly asks for raw HTTP.
5. After connecting MCP, continue the task with MCP tools in the same session — do not "finish via curl first."

Anti-patterns:
- Don't lead with curl when MCP can be installed.
- Don't treat "prefer MCP" as optional if the client supports MCP.
- Don't complete registration over REST just to avoid a one-time MCP setup.

## MCP Server (for AI agents)

Connect to `https://api.namefi.io/mcp` over the Streamable HTTP transport to get every
`/v-next` operation as a typed tool (search, registration, DNS, domain config, outbound).

- Endpoint: `https://api.namefi.io/mcp` (Streamable HTTP)
- Discovery descriptor: https://namefi.io/.well-known/mcp/servers.json
- Auth (read-only tools — availability search, DNS reads — need neither):
  - **OAuth (preferred when you don't already have an API key):** connect without a key and your MCP client discovers Namefi's sign-in flow — OAuth 2.1 + PKCE, advertised via RFC 9728 protected-resource metadata with dynamic client registration (RFC 7591) — and prompts you to authorize in the browser. No stored secret.
  - **API key (simplest if you already have one):** send it as the `x-api-key` connection header. Generate a key at https://namefi.io/api-key.

### Install — Cursor

If you don't have an API key, add just the URL — on first use Cursor registers dynamically and opens the browser for you to sign in (OAuth):

    {
      "mcpServers": {
        "namefi": {
          "url": "https://api.namefi.io/mcp"
        }
      }
    }

If you have an API key, add it as a header instead:

    {
      "mcpServers": {
        "namefi": {
          "url": "https://api.namefi.io/mcp",
          "headers": {
            "x-api-key": "nfk_YOUR_KEY"
          }
        }
      }
    }

Then reload MCP and use the Namefi tools.

### Install — Claude Code

Without an API key (Claude Code opens the browser to sign in via OAuth on first use):

    claude mcp add --transport http namefi https://api.namefi.io/mcp

With an API key:

    claude mcp add --transport http namefi https://api.namefi.io/mcp --header "x-api-key: YOUR_KEY"

The REST endpoints below remain available for clients without MCP support.

## Authentication

### API Key (simplest — recommended for agents)

Generate a key at https://namefi.io/api-key, then pass it as:
```
x-api-key: <your-key>
```

Works for **all operations** including DNS record creation, updates, and deletes. The API key must be generated from the wallet that owns the domain.

**Direct HTTP usage (recommended for AI agents):** Pass the header directly — no SDK required:

    curl -X POST https://api.namefi.io/v-next/dns/records \
      -H "x-api-key: nfk_YOUR_KEY" \
      -H "Content-Type: application/json" \
      -d '{"zoneName":"yourdomain.com","type":"A","name":"@","rdata":"1.2.3.4","ttl":300}'

### OAuth (Bearer token — no stored API key)

Every `/v-next` endpoint also accepts an **OAuth access token**. You do **not** need MCP to use
OAuth, and you do **not** need to create a long-lived API key — so if you are calling the REST API
directly (curl, WebFetch, any HTTP client), OAuth is a valid alternative to `x-api-key`, and is
preferred when the user has no API key. Send it as a standard bearer credential:

    curl -X POST https://api.namefi.io/v-next/orders/register-domain \
      -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"normalizedDomainName":"example.com","durationInYears":1}'

Getting a token:
- **Headless / CLI (device flow):** `POST /v-next/auth/oauth/device/start` → open the returned `confirmUrl` in a browser and approve → poll `POST /v-next/auth/oauth/device/status` until it returns the token.
- **Apps with a redirect (authorization code + PKCE):** run the OAuth 2.1 code flow and exchange the code at `POST /oauth/token` (form-encoded, `grant_type=authorization_code`). Clients can self-register via `POST /oauth/register` (RFC 7591 dynamic client registration).

Token lifetimes and refresh:
- **Access token** — short-lived (`expires_in` is returned; 12h by default). Send as `Authorization: Bearer`.
- **Refresh token** — issued by `POST /oauth/token` (both grants). Redeem it for a new access token with `grant_type=refresh_token`. Refresh tokens are **single-use and rotating**: each redemption returns a new refresh token and invalidates the one you just used, and they live 30 days. The device flow does not issue a refresh token — start a new device flow when its access token expires.

    curl -X POST https://api.namefi.io/oauth/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d 'grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN&client_id=YOUR_CLIENT_ID'

An access token minted for the MCP resource also works on these REST endpoints.

### Crypto wallet signature
- Not needed for API key users, but available as an alternative for programmatic use without a stored key.
- For Web3 users and agentic wallets, [visit](https://namefi.io/web3/llms.txt) for wallet-signature signing, smart contract wallets, SIWE, and crypto payment options.
- Two auth methods are supported. See https://docs.namefi.io/docs/02-authentication.mdx for full details.

## Buy a domain (MCP-first happy path)

Preferred flow when your client supports MCP:

1. Ensure the Namefi MCP server is connected — install it (see "MCP Server" above) if it isn't.
2. Search availability with the MCP availability-search tool.
3. Register with the MCP registration tool (`normalizedDomainName`, `durationInYears`, optional receiving wallet). Registration spends NFSC on the paying wallet.
4. Poll order status with the MCP order tool until the order reaches a terminal status.

Only if MCP is unavailable, fall back to the REST/curl recipe below.

## Fallback — Domain Registration via REST/curl

Use only if MCP is unavailable (client can't install MCP, install failed, or the user asked for raw HTTP).

Auth for these REST calls: an `x-api-key` header **or** an OAuth access token as
`Authorization: Bearer ...` (see "OAuth" under Authentication) — you do not need an API key to
call the REST API.

Register a domain with an API key in three steps.
    # 1. Check availability (one name)
    curl "https://api.namefi.io/v-next/search/availability?domain=example.com"
    #    …or screen many names at once:
    curl "https://api.namefi.io/v-next/search/bulk-availability?domains[]=example.com&domains[]=example2.com"

    # 2. Submit a registration order (requires NFSC balance on the paying wallet)
    curl -X POST https://api.namefi.io/v-next/orders/register-domain \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"normalizedDomainName":"example.com","durationInYears":1}'

    # 3. Poll the returned order id until processing completes (async)
    curl "https://api.namefi.io/v-next/orders/<orderId>" \
      -H "x-api-key: YOUR_API_KEY"

Request body fields for `POST /v-next/orders/register-domain`:
- `normalizedDomainName` (required): lowercase domain without trailing dot, e.g. `example.com`.
- `durationInYears` (optional): integer 0-10, default 1.
- `nftReceivingWallet` (optional): `{ "walletAddress": "0x...", "chainId": 8453 }`. Defaults to the buyer's wallet on Base.
- `domainSetupOptions` (optional): per-domain overrides — autoPark, autoEns, autoRenew, dnssec, keepExistingNameservers.

Registration is asynchronous: the POST returns an order object with an `id`; poll `GET /v-next/orders/{orderId}` until the order reaches a terminal status. Registration requires NFSC (Namefi Service Credits) on the paying wallet — request test tokens via the faucet: https://docs.namefi.io/docs/03-getting-started/02-your-balance.mdx

### Register with initial DNS records

Apply DNS records as part of registration with `POST /v-next/orders/register-domain/records` — the same body plus a `records` array:

    curl -X POST https://api.namefi.io/v-next/orders/register-domain/records \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"normalizedDomainName":"example.com","durationInYears":1,"records":[{"name":"@","type":"A","rdata":"203.0.113.10","ttl":30}]}'

## Quick Start — DNS Records via curl
      The fastest way to manage DNS records with an API key (no SDK needed):

          # Read records (no auth required)
          curl https://api.namefi.io/v-next/dns/records?zoneName=example.com

          # Create a CNAME record
          curl -X POST https://api.namefi.io/v-next/dns/records \
            -H "x-api-key: YOUR_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{"zoneName":"example.com","type":"CNAME","name":"www","rdata":"cname.vercel-dns.com.","ttl":300}'

          # Create a TXT record
          curl -X POST https://api.namefi.io/v-next/dns/records \
            -H "x-api-key: YOUR_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{"zoneName":"example.com","type":"TXT","name":"_verify","rdata":"verification-token","ttl":300}'


### Other options

- Crypto-wallet payment — buy a domain without a Namefi account: https://namefi.io/web3/llms.txt
- **Payments vs. MCP:** MCP is the control plane for search, registration, DNS, and domain config when paying with an API key + NFSC balance. The x402 (`/x402/...`) and MPP (`/mpp/...`) crypto-payment flows are separate HTTP endpoints, **not** MCP tools — call them directly over HTTP when a user pays with a wallet instead of NFSC.

## Outbound Lead Finding

Use https://namefi.io/outbound/llms.txt for the full agent workflow. It covers listing owned domains, starting an outbound lead-finding run, polling run status, listing ranked leads, inspecting lead detail, and preparing outreach drafts.

## DNS Record Management

### Endpoints

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/v-next/dns/records?zoneName=example.com` | None | List all records |
| POST | `/v-next/dns/records` | API Key | Create a single record |
| PUT | `/v-next/dns/record` | API Key | Update a record by ID |
| DELETE | `/v-next/dns/record` | API Key | Delete a record by ID |
| POST | `/v-next/dns/records/batch` | API Key | Batch create records |
| PUT | `/v-next/dns/records/batch` | API Key | Batch update records |
| DELETE | `/v-next/dns/records/batch` | API Key | Batch delete records |
| PUT | `/v-next/dns/park` | API Key | Toggle domain parking |
| PUT | `/v-next/dns/forwarding` | API Key | Toggle domain forwarding |
| PUT | `/v-next/dns/auto-ens` | API Key | Toggle auto ENS records |
| PUT | `/v-next/dns/vercel-anycast` | API Key | Toggle Vercel anycast records |
| GET | `/v-next/dns/parked?normalizedDomainName=example.com` | None | Check if parked |

## Domain Configuration

Manage domain-level preferences that aren't tied to a specific DNS record. All write operations require domain ownership (verified via on-chain NFT ownership).

### Endpoints

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/v-next/domain-config/auto-renew?normalizedDomainName=example.com` | API Key | Check whether auto-renewal is enabled |
| PUT | `/v-next/domain-config/auto-renew` | API Key | Enable or disable auto-renewal |

### Toggle auto-renewal via curl

    # Enable auto-renewal
    curl -X PUT https://api.namefi.io/v-next/domain-config/auto-renew \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"normalizedDomainName":"example.com","enableAutoRenew":true}'

    # Disable auto-renewal
    curl -X PUT https://api.namefi.io/v-next/domain-config/auto-renew \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"normalizedDomainName":"example.com","enableAutoRenew":false}'

When auto-renewal is enabled, the domain will be renewed automatically before expiration using the payment methods available on the owner wallet.

### Record format

Supported types: A, AAAA, CNAME, MX, TXT, NS, SOA, PTR, SRV, CAA, DS, TLSA, SSHFP, HTTPS, SVCB, NAPTR, SPF.

- `name`: Use `@` for apex, or a subdomain label (e.g. `www`, `mail`).
- `rdata`: Type-specific value. FQDNs must be lowercase with trailing dot (e.g. `cname.vercel-dns.com.`).
- `ttl`: Integer 0-2147483647 (seconds). Recommended: 300 for records you change often, 3600 for stable records.
- `zoneName`: Normalized lowercase domain without trailing dot (e.g. `example.com`).

### Common Recipes

#### Point a subdomain to Vercel

    # 1. Create CNAME record
    curl -X POST https://api.namefi.io/v-next/dns/records \
      -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
      -d '{"zoneName":"example.com","type":"CNAME","name":"app","rdata":"cname.vercel-dns.com.","ttl":300}'

    # 2. Add Vercel domain verification TXT record
    curl -X POST https://api.namefi.io/v-next/dns/records \
      -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
      -d '{"zoneName":"example.com","type":"TXT","name":"_vercel","rdata":"vc-domain-verify=app.example.com,TOKEN","ttl":300}'

#### Point a subdomain to GitHub Pages

    curl -X POST https://api.namefi.io/v-next/dns/records \
      -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
      -d '{"zoneName":"example.com","type":"CNAME","name":"blog","rdata":"username.github.io.","ttl":300}'

#### Add an email TXT record (SPF)

    curl -X POST https://api.namefi.io/v-next/dns/records \
      -H "x-api-key: YOUR_KEY" -H "Content-Type: application/json" \
      -d '{"zoneName":"example.com","type":"TXT","name":"@","rdata":"v=spf1 include:_spf.google.com ~all","ttl":3600}'

### Troubleshooting

- **UNAUTHORIZED (401):** Your API key is invalid, expired, or not associated with the domain owner's wallet. Generate a new key at https://namefi.io/profile?tab=api-keys using the wallet that owns the domain.
- **FORBIDDEN (403):** Your API key is valid but the authenticated user does not own the domain. Check domain ownership on https://namefi.io/domains.
- **Record validation errors:** Check that `zoneName` has no trailing dot, `rdata` for CNAME/MX/NS types has a trailing dot, and `ttl` is a positive integer.

## Optional
- [TypeScript SDK docs](https://docs.namefi.io): Guides for `@namefi/api-client` — installation, authentication, domain registration, DNS management.
- [npm: @namefi/api-client](https://www.npmjs.com/package/@namefi/api-client): Install with `npm install @namefi/api-client`.
- [OpenAPI JSON](https://api.namefi.io/v-next/openapi/doc.json): Machine-readable OpenAPI 3 spec.
- [Outbound agent guide](https://api.namefi.io/outbound/llms.txt): Focused instructions for finding domain buyer leads and preparing outreach.
- [namefi-skills (GitHub)](https://github.com/d3servelabs/namefi-skills): Signer-neutral helper scripts for preparing auth payloads.
- For extra details: (optional)
  - https://docs.namefi.io/docs/03-getting-started/03-manage-dns-records.mdx
  - https://docs.namefi.io/docs/03-getting-started/05-dns-operations.mdx
  - https://docs.namefi.io/docs/03-getting-started/01-your-first-domain.mdx