Transfer Subname

Transfer ownership of a subname to a new Ethereum address.

Endpoint

POST /api/subnames/{parent}/{name}/transfer

Authentication

Ownership verification required — Either via SIWE or by providing the current owner address.

Request Body

{
  "newOwner": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
  "currentOwner": "0x701B4937e6c943789ffA74CC8601813b2D87B454"
}

Field	Type	Required	Description
newOwner	string	✅	Ethereum address of new owner
currentOwner	string	❌	Current owner address (for verification)

Response

{
  "success": true,
  "parent": "aboutme.eth",
  "name": "alice",
  "fullName": "alice.aboutme.eth",
  "newOwner": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
  "transferred": {
    "success": true,
    "previousOwner": "0x701B4937e6c943789ffA74CC8601813b2D87B454"
  },
  "timestamp": "2024-02-10T14:30:00.000Z"
}

Examples

cURL

# Transfer with owner verification
curl -X POST "https://api.web3identity.com/api/subnames/aboutme.eth/alice/transfer" \
  -H "Content-Type: application/json" \
  -d '{
    "newOwner": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0",
    "currentOwner": "0x701B4937e6c943789ffA74CC8601813b2D87B454"
  }'

# Transfer with SIWE authentication (recommended)
curl -X POST "https://api.web3identity.com/api/subnames/aboutme.eth/alice/transfer" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "newOwner": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0"
  }'

JavaScript

async function transferSubname(parent, name, newOwner, token = null) {
  const headers = {
    'Content-Type': 'application/json'
  };
  
  if (token) {
    headers['Authorization'] = `Bearer ${token}`;
  }
  
  const response = await fetch(
    `https://api.web3identity.com/api/subnames/${parent}/${name}/transfer`,
    {
      method: 'POST',
      headers,
      body: JSON.stringify({ newOwner })
    }
  );
  
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Transfer failed');
  }
  
  return response.json();
}

// Transfer to new owner
const result = await transferSubname(
  'aboutme.eth',
  'alice',
  '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
  siweToken
);

console.log(`Transferred to: ${result.newOwner}`);

Transfer with Confirmation

async function transferWithConfirmation(parent, name, newOwner, signer) {
  // 1. Get current details
  const details = await fetch(
    `https://api.web3identity.com/api/subnames/${parent}/${name}`
  ).then(r => r.json());
  
  const currentOwner = await signer.getAddress();
  
  // 2. Verify caller is owner
  if (details.owner.toLowerCase() !== currentOwner.toLowerCase()) {
    throw new Error('You do not own this subname');
  }
  
  // 3. Authenticate
  const nonceRes = await fetch(
    'https://api.web3identity.com/api/auth/nonce',
    { 
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ address: currentOwner })
    }
  );
  const { message } = await nonceRes.json();
  const signature = await signer.signMessage(message);
  
  const { token } = await fetch(
    'https://api.web3identity.com/api/auth/verify',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message, signature })
    }
  ).then(r => r.json());
  
  // 4. Execute transfer
  return transferSubname(parent, name, newOwner, token);
}

Important Notes

Transfer is Immediate

• Transfer takes effect immediately
• The new owner gains full control
• Records and expiration are preserved
• This action cannot be undone without the new owner's consent

Validation

Check	Description
Address format	newOwner must be valid Ethereum address
Ownership	Only current owner can transfer
Existence	Subname must be registered

Error Responses

Status	Code	Description
400	BAD_REQUEST	Missing newOwner or invalid address
403	NOT_OWNER	Caller is not the current owner
404	NOT_FOUND	Subname does not exist
429	RATE_LIMITED	Rate limit exceeded
500	TRANSFER_ERROR	Internal server error

Related Endpoints

• Get Details — Check current ownership
• SIWE Authentication — Authenticate for secure transfer
• By Owner — List names by owner