Getting started
Manage DNS Records
Full flow for registering with records, reading existing records, and updating DNS
This guide covers the full DNS flow:
- Register a domain with initial records.
- Fetch the current zone records.
- Update existing records in batch.
- Create any missing records.
- Create any missing records.
- Verify final state.
End-to-end example
import { createNamefiClient } from '@namefi/api-client';
import { setTimeout as sleep } from 'node:timers/promises';
const client = createNamefiClient({
authentication: {
apiKey: process.env.NAMEFI_API_KEY!,
type: 'API_KEY',
},
logger: true,
});
const zoneName = 'example.com';
// 1) Register domain and seed initial DNS records
const order = await client.orders.registerWithRecords({
normalizedDomainName: zoneName,
durationInYears: 1,
records: [
{ name: '@', type: 'A', rdata: '203.0.113.10', ttl: 300 },
{ name: 'www', type: 'CNAME', rdata: 'example.com.', ttl: 300 },
],
});
// 2) Wait for order processing to finish
const terminalStatuses = new Set([
'SUCCEEDED',
'FAILED',
'CANCELLED',
'PARTIALLY_COMPLETED',
]);
while (true) {
const current = await client.orders.getOrder({ orderId: order.id });
if (terminalStatuses.has(current.order.status)) {
console.log('Final order status:', current.order.status);
break;
}
await sleep(5_000);
}
// 3) Check existing records
const existing = await client.dnsRecords.getRecords({ zoneName });
console.table(
existing.map((r) => ({
id: r.id,
name: r.name,
type: r.type,
rdata: r.rdata,
ttl: r.ttl,
})),
);
// 4) Update existing records by ID
const apexA = existing.find((r) => r.name === '@' && r.type === 'A');
const wwwCname = existing.find((r) => r.name === 'www' && r.type === 'CNAME');
const recordsToUpdate = [];
if (apexA) {
recordsToUpdate.push({
id: apexA.id,
rdata: '198.51.100.42',
ttl: 300,
});
}
if (wwwCname) {
recordsToUpdate.push({
id: wwwCname.id,
rdata: 'example.com.',
ttl: 300,
});
}
if (recordsToUpdate.length > 0) {
await client.dnsRecords.updateRecords({
zoneName,
records: recordsToUpdate,
});
}
// 5) Create records that do not exist yet
const recordsToCreate = [];
if (!apexA) {
recordsToCreate.push({
name: '@',
type: 'A',
rdata: '198.51.100.42',
ttl: 300,
});
}
if (!wwwCname) {
recordsToCreate.push({
name: 'www',
type: 'CNAME',
rdata: 'example.com.',
ttl: 300,
});
}
if (recordsToCreate.length > 0) {
await client.dnsRecords.createRecords({
zoneName,
records: recordsToCreate,
});
}
// 6) Verify final records
const finalRecords = await client.dnsRecords.getRecords({ zoneName });
console.table(
finalRecords.map((r) => ({
name: r.name,
type: r.type,
rdata: r.rdata,
ttl: r.ttl,
})),
);Notes
updateRecordsonly updates existing records and requiresidfor each record.- Use
getRecordsfirst, then build the update payload from returned IDs. - Use
createRecordsfor records that do not exist yet. - All batch operations are scoped to one
zoneNameper request.
Managing Your Balance
Request faucet NFSC (test) and check your balance across chains
Get NFSC balance GET
Retrieve NFSC (Namefi Stable Coin) balance across all supported blockchain chains for the authenticated user's linked wallet addresses. Returns both raw contract values and human-readable USD amounts.