DNS Operations

This guide covers DNS operations beyond the full-flow example. All DNS mutation operations require domain ownership (verified via on-chain NFT ownership). The client handles authentication automatically with both API_KEY and EIP712 auth types.

Quick start with curl

You can manage DNS records with just curl and an API key — no SDK installation required:

# List existing records (no auth needed)
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":"some-verification-token","ttl":300}'

This is the recommended approach for AI agents and scripts that need simple DNS management.

Read records

Fetch all DNS records for a zone:

import { createNamefiClient } from '@namefi/api-client';

const client = createNamefiClient({
  authentication: {
    apiKey: process.env.NAMEFI_API_KEY!,
    type: 'API_KEY',
  },
  logger: true,
});

const records = await client.dnsRecords.getRecords({
  zoneName: 'example.com',
});

for (const r of records) {
  console.log(`${r.name} ${r.type} ${r.rdata} (TTL: ${r.ttl}, ID: ${r.id})`);
}

Create a single record

await client.dnsRecords.createDnsRecord({
  zoneName: 'example.com',
  type: 'A',
  name: '@',
  rdata: '203.0.113.10',
  ttl: 300,
});

Update a single record

Update an existing record by its ID. Fetch records first to get the ID:

const records = await client.dnsRecords.getRecords({
  zoneName: 'example.com',
});

const apex = records.find((r) => r.name === '@' && r.type === 'A');

if (apex) {
  await client.dnsRecords.updateRecord({
    id: apex.id,
    zoneName: 'example.com',
    rdata: '198.51.100.42',
    ttl: 600,
  });
}

Delete a single record

await client.dnsRecords.deleteRecord({
  id: apex.id,
  zoneName: 'example.com',
});

Batch delete records

Delete multiple records at once by their IDs:

const records = await client.dnsRecords.getRecords({
  zoneName: 'example.com',
});

const txtRecords = records.filter((r) => r.type === 'TXT');

if (txtRecords.length > 0) {
  await client.dnsRecords.deleteRecords({
    zoneName: 'example.com',
    recordsIds: txtRecords.map((r) => r.id),
  });
}

Domain parking

Park a domain to serve a default landing page. This replaces DNS records with parking records:

// Park a domain
await client.dnsRecords.parkDomain({
  normalizedDomainName: 'example.com',
  overrideExistingRecords: true,
});

// Check if a domain is parked
const { parked } = await client.dnsRecords.isDomainParked({
  normalizedDomainName: 'example.com',
});

console.log('Parked:', parked);

Toggle parking

Enable or disable parking without removing existing records:

// Disable parking, keep existing records
await client.dnsRecords.toggleDomainParking({
  normalizedDomainName: 'example.com',
  enableParking: false,
  overrideExistingRecords: false,
});

// Re-enable parking
await client.dnsRecords.toggleDomainParking({
  normalizedDomainName: 'example.com',
  enableParking: true,
  overrideExistingRecords: false,
});

Supported record types

The API supports standard DNS record types including:

A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, SOA

Notes

All mutation operations (create, update, delete, park, toggleParking) use EIP-712 signing under the hood. The client handles this transparently.
updateRecord and updateRecords require the record id — use getRecords first.
overrideExistingRecords on parking operations controls whether current records are replaced or preserved.
All batch operations are scoped to a single zoneName per request.

Troubleshooting

UNAUTHORIZED (401) on write operations

API key not associated with domain owner: The API key must be generated from the wallet that owns the domain on-chain. Go to API Keys management, connect the wallet that holds the domain NFT, and generate a new key.
Expired or revoked key: Generate a fresh API key.
Wrong base URL: Use https://api.namefi.io/v-next/ (production) or https://backend.astra.namefi.io/v-next/ (SDK default). Both point to the same backend.

FORBIDDEN (403) on write operations

Your API key is valid but the authenticated wallet does not own the target domain. Verify ownership at My Domains.

SDK alternative: direct HTTP

If you encounter issues with the @namefi/api-client SDK, you can always fall back to direct HTTP with curl or any HTTP client. Pass your API key as the x-api-key header. See the curl quick start above.

DNS Operations

On this page