# Namefi API

> Namefi lets you register traditional domains as NFTs and manage their DNS records via API.

## Docs

- [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-api-skills (GitHub)](https://github.com/d3servelabs/namefi-api-skills): Signer-neutral helper scripts for preparing auth payloads.
- Buy domain (X402): https://api.namefi.io/x402/domain/{domainName}
- Buy domain (MPP): https://api.namefi.io/mpp/domain/{domainName}?nftReceivingWalletAddress={nftReceivingWalletAddress}

## Base URLs

| Environment | Base URL |
|-------------|----------|
| Production  | `https://api.namefi.io/v-next/` (alias: `https://backend.astra.namefi.io/v-next/`) |
| Development | `https://api.namefi.dev/v-next/` |

**Important:** The SDK default base URL is `https://backend.astra.namefi.io`. Both `api.namefi.io` and `backend.astra.namefi.io` point to the same backend.

## 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}'

## Authentication

Three auth methods are supported. See https://docs.namefi.io/docs/02-authentication for full details.

### 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}'

### Crypto wallet signature (EIP-712)
- 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://api.namefi.io/llms.txt/web3) for details on signing requests with EIP-712, including support for smart contract wallets (ERC-1271 / EIP-7702) and SIWE authentication.

## Domain Registration

See https://docs.namefi.io/docs/03-getting-started/01-your-first-domain

Key operations:
- `GET /v-next/search/availability?domain=example.com` — check availability
- `GET /v-next/search/bulk-availability?domains[]=example.com&domains[]=example2.com` — check bulk availability
- `POST /v-next/orders/register-domain` — register a domain
- `POST /v-next/orders/register-domain/records` — register with initial DNS records
- `GET /v-next/orders/{orderId}` — poll order status (async processing)

Registration requires NFSC (Namefi Service Credits). Request test tokens via the faucet: https://docs.namefi.io/docs/03-getting-started/02-your-balance

## Outbound Lead Finding

Use https://api.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

See https://docs.namefi.io/docs/03-getting-started/03-manage-dns-records and https://docs.namefi.io/docs/03-getting-started/05-dns-operations

All DNS write operations require domain ownership (verified via on-chain NFT ownership). The API key must belong to the wallet that owns the domain.

### Endpoints

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/v-next/dns/records?zoneName=example.com` | None | List all records |
| POST | `/v-next/dns/records` | API Key or EIP-712 | Create a single record |
| PUT | `/v-next/dns/record` | API Key or EIP-712 | Update a record by ID |
| DELETE | `/v-next/dns/record` | API Key or EIP-712 | Delete a record by ID |
| POST | `/v-next/dns/records/batch` | API Key or EIP-712 | Batch create records |
| PUT | `/v-next/dns/records/batch` | API Key or EIP-712 | Batch update records |
| DELETE | `/v-next/dns/records/batch` | API Key or EIP-712 | Batch delete records |
| PUT | `/v-next/dns/park` | API Key or EIP-712 | Toggle domain parking |
| PUT | `/v-next/dns/forwarding` | API Key or EIP-712 | Toggle domain forwarding |
| PUT | `/v-next/dns/auto-ens` | API Key or EIP-712 | Toggle auto ENS records |
| PUT | `/v-next/dns/vercel-anycast` | API Key or EIP-712 | 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 or EIP-712 | Check whether auto-renewal is enabled |
| PUT | `/v-next/domain-config/auto-renew` | API Key or EIP-712 | 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`).

## x402 Payments (HTTP 402)

Buy a domain with stablecoin (USDC) using the [x402 protocol](https://x402.org). No Namefi account or EIP-712 signing required — the buyer's wallet signs an EIP-3009 `transferWithAuthorization`.

- `GET /x402/domain/{domainName}` — without an `X-PAYMENT` header, returns `402 Payment Required` with payment options (network, asset, amount in USDC). With a valid `X-PAYMENT` header, verifies the signature, starts the registration workflow, and settles payment.
  - Optional query params: `years` (1-10, default 1), `nftReceivingWalletAddress` (defaults to the buyer wallet).
- `GET /x402/purchase/{purchaseId}` — poll purchase status. Returns JSON when `?content-type=json` or the `Accept` header isn't HTML; otherwise redirects to the frontend progress page.
- namefi-api-skills have the full details about all possible payment options.

## MPP (Machine Payable Protocol)

Buy a domain or sign in using the MPP payment-challenge flow. The first request returns `402 Payment Required` with a signed challenge; the client signs it (e.g. via the [`mppx`](https://www.npmjs.com/package/mppx) CLI: `mppx sign`) and replays the request with the resulting `Authorization` header to complete the operation.

- `GET /mpp/domain/{domainName}` — register a domain via MPP. Required query param: `nftReceivingWalletAddress` (checksummed). Optional: `years` (1-10, default 1). Without auth → 402 with challenge + price metadata. With a valid signed credential → instant registration.
- `GET /mpp/sign-in` — MPP-authenticated sign-in. Without auth → 402 with challenge. With a valid signed credential → returns the sign-in result.

### 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

- [OpenAPI JSON](https://api.namefi.io/v-next/openapi/doc.json)