Update Subname Records

Update ENS text records for a subname you own. Requires SIWE authentication.

Endpoint

PUT /api/subnames/{parent}/{name}

Authentication

SIWE Required — You must authenticate with the wallet that owns the subname.

Authorization: Bearer <jwt_token>

Request Body

{
  "records": {
    "description": "Updated description",
    "url": "https://newsite.com",
    "com.twitter": "@newhandle",
    "com.github": "newgithub",
    "avatar": "ipfs://QmNewHash..."
  }
}

Field	Type	Required	Description
records	object	✅	Key-value pairs of ENS text records

Common Record Keys

Key	Description	Example
description	Profile bio	"Web3 developer"
url	Website URL	"https://example.com"
avatar	Avatar image (IPFS/HTTP)	"ipfs://Qm..."
com.twitter	Twitter handle	"@username"
com.github	GitHub username	"username"
com.discord	Discord username	"user#1234"
org.telegram	Telegram username	"@username"
email	Email address	"user@example.com"
notice	Special notice	"Not for sale"

Response

{
  "success": true,
  "parent": "aboutme.eth",
  "name": "alice",
  "fullName": "alice.aboutme.eth",
  "updated": {
    "success": true,
    "recordsUpdated": 4
  },
  "updatedBy": "0x701B4937e6c943789ffA74CC8601813b2D87B454",
  "timestamp": "2024-02-10T14:30:00.000Z"
}

Examples

cURL

# First, get SIWE token (see Auth docs)
TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# Update records
curl -X PUT "https://api.web3identity.com/api/subnames/aboutme.eth/alice" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "records": {
      "description": "Web3 developer & ENS enthusiast",
      "com.twitter": "@alice_eth"
    }
  }'

JavaScript

async function updateRecords(parent, name, records, token) {
  const response = await fetch(
    `https://api.web3identity.com/api/subnames/${parent}/${name}`,
    {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ records })
    }
  );
  
  if (response.status === 401) {
    throw new Error('Authentication required - please sign in with SIWE');
  }
  
  if (response.status === 403) {
    throw new Error('You do not own this subname');
  }
  
  return response.json();
}

// Update with SIWE session
const result = await updateRecords(
  'aboutme.eth',
  'alice',
  {
    description: 'Updated bio',
    url: 'https://newsite.com',
    'com.twitter': '@newhandle'
  },
  siweToken
);

Full Update Flow with SIWE

import { SiweMessage } from 'siwe';

async function updateSubnameWithAuth(parent, name, records, signer) {
  // 1. Get nonce
  const nonceRes = await fetch(
    'https://api.web3identity.com/api/auth/nonce',
    { method: 'POST' }
  );
  const { nonce, message: siweMessage } = await nonceRes.json();
  
  // 2. Sign message
  const signature = await signer.signMessage(siweMessage);
  
  // 3. Verify and get token
  const verifyRes = await fetch(
    'https://api.web3identity.com/api/auth/verify',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message: siweMessage, signature })
    }
  );
  const { token } = await verifyRes.json();
  
  // 4. Update records
  return updateRecords(parent, name, records, token);
}

Ownership Verification

The API verifies that:

1. Your JWT token is valid and not expired
2. The address in your token matches the subname's owner
3. The subname exists

If any check fails, you'll receive an appropriate error.

Error Responses

Status	Code	Description
400	BAD_REQUEST	Invalid request body
401	UNAUTHORIZED	No SIWE token provided
401	INVALID_TOKEN	Token is invalid or expired
403	NOT_OWNER	Authenticated address doesn't own this subname
404	NOT_FOUND	Subname does not exist
429	RATE_LIMITED	Rate limit exceeded
500	SUBNAME_ERROR	Internal server error

Related Endpoints

• SIWE Authentication — Get authentication token
• Get Profile — View current records
• Get Details — Basic subname info