# 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 — every MCP tool call requires it. Connecting without credentials returns HTTP 401 whose JSON body carries a `how_to_fix` block repeating these exact instructions, so a bare 401 is never a dead end:
  - **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). Expect a browser window to open: the user signs in and clicks approve, then your client retries with the token automatically. No stored secret. If you are an agent, ask your user to complete the browser approval before continuing.
  - **API key (simplest if you already have one; best for headless/unattended runs):** send it as the `x-api-key` connection header. Generate a key at https://namefi.io/api-key.
  - **No credentials and only checking availability?** The REST search endpoint is open — `GET https://api.namefi.io/v-next/search/availability?domain=example.com` needs no auth (the search-only exception to the MCP-first policy). Connect MCP or add an API key when you move on to registration, DNS, or account operations.

### 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: $NAMEFI_API_KEY"

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

## Authentication

If a request is rejected for missing or invalid credentials, the response tells you how to proceed: REST `/v-next` endpoints return 401 with the remediation appended to the error `message` (API-key page, header name, OAuth pointer), and the MCP endpoint returns 401 with a machine-parseable `how_to_fix` block plus a `WWW-Authenticate` challenge your MCP client uses to start the browser sign-in. Read the error body before giving up — it is the fastest path to the fix.

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

Generate a key at https://namefi.io/api-key. Set it as `NAMEFI_API_KEY` in your shell (`export NAMEFI_API_KEY=nfk_...`) and pass it as the header:
```
x-api-key: $NAMEFI_API_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: $NAMEFI_API_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 $NAMEFI_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.

## Hand off to a human (agent → human checkout)

Use this when you cannot complete the purchase yourself — the user has no API key, no funded
wallet and no saved card, or a call came back with a payment-blocked error. You compose the cart,
the human signs in and pays, and you track the result.

1. Give the human a cart link. Comma-separate multiple domains:

       https://namefi.io/cart/add-from-url?add_to_cart=example.com,example2.com

   The page adds the domains and redirects to `/cart` once the human clicks its confirm button.
   No account is needed to build the cart — a guest cart is held locally and merges into the
   user's account when they sign in.

2. The human pays in the cart and lands on the order's own durable URL, which they can re-open
   later and read the order id from:

       https://namefi.io/orders/<orderId>

3. Track the outcome. Which option applies depends on whether you hold a token:

   - **You hold an access token for that user** (see "OAuth" above — the device flow exists for
     exactly this): poll the order until it reaches a terminal status. `GET /v-next/orders/items`
     lists that user's order items, so you need not have the human relay the order id at all.

         curl https://api.namefi.io/v-next/orders/<orderId> \
           -H "Authorization: Bearer $NAMEFI_ACCESS_TOKEN"

   - **You are anonymous** (no API key, no token): you cannot read order status.
     `GET /v-next/orders/{orderId}` requires authentication and returns only orders owned by the
     caller. Either ask the human to report the status from the order URL, or run the device flow
     first so the case above applies.

When a call is blocked for payment reasons, its error body already carries the URL to send the
human to (for example an NFSC top-up or add-card link). Surface that link rather than composing
your own.

## 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: $NAMEFI_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: $NAMEFI_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: $NAMEFI_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: $NAMEFI_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: $NAMEFI_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: $NAMEFI_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: $NAMEFI_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: $NAMEFI_API_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: $NAMEFI_API_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: $NAMEFI_API_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: $NAMEFI_API_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