NameStone Docs

Set Name

Set Names (Batch)

This POST route creates multiple names (subdomains) for a given domain in a single transaction. This is a batch version of the set-name endpoint that provides significant performance improvements when setting multiple names at once. It has a limit of 50 names at once.

Parameters

Parameter	Type	Required	Description
`domain`	string	Yes	The domain (e.g. "testbrand.eth").
`names`	array	Yes	Array of name objects to create/update. Each object has the same structure as the `set-name` endpoint. Limit 50.

Name Object Structure

Each object in the names array supports the same parameters as the set-name endpoint:

Parameter	Type	Required	Description
`name`	string	Yes	The name being set, i.e., the "example" in example.testbrand.eth.
`address`	string	No	The Ethereum address the name points to.
`contenthash`	string	No	The link for an IPFS or IPNS website.
`text_records`	object	No	An object containing key-value pairs of the text records to be set.
`coin_types`	object	No	An object containing key-value pairs of L2 chains and their resolved address.

Batch Processing

Transaction Safety: All names are processed in a single database transaction
All-or-Nothing: If any name fails, the entire batch is rolled back
Name Limits: The batch size is validated against your domain's name limit
Mixed Operations: Can create new names and update existing names in the same batch

Response Format

Success Response

{
  "success": true,
  "processed": 3,
  "results": [
    {
      "index": 0,
      "name": "alice",
      "success": true,
      "subdomainId": 123
    },
    {
      "index": 1,
      "name": "bob",
      "success": true,
      "subdomainId": 124
    },
    {
      "index": 2,
      "name": "charlie",
      "success": true,
      "subdomainId": 125
    }
  ]
}

Error Response

{
  "error": "Batch operation failed",
  "processed": 0,
  "errors": [
    {
      "index": 1,
      "name": "invalid..name",
      "error": "Invalid ens name"
    }
  ],
  "total": 3
}

Multichain Address Resolution

Namestone supports address resolution on any L2 Chains Supported by ENS.
To add an address to an L2 chain use its coin_type. (See coin_type column in the above link) .
Or convert chain_id to coin_type using the following typescript template.

Curl Example

curl -X POST \
     -H 'Content-Type: application/json' \
     -H 'Authorization: YOUR_API_KEY' \
     -d '{
          "domain": "namestone.xyz",
          "names": [
            {
              "name": "alice",
              "address": "0x534631Bcf33BDb069fB20A93d2fdb9e4D4dD42CF",
              "text_records": {
                "com.twitter": "alice_crypto",
                "description": "Alice profile",
                "avatar": "https://imagedelivery.net/UJ5oN2ajUBrk2SVxlns2Aw/alice-avatar.png"
              }
            },
            {
              "name": "bob",
              "address": "0x1234567890123456789012345678901234567890",
              "coin_types": {
                "2147483785": "0x1234567890123456789012345678901234567890",
                "2147492101": "0x1234567890123456789012345678901234567890"
              },
              "text_records": {
                "com.github": "bob-dev",
                "url": "https://bob.dev"
              }
            },
            {
              "name": "charlie",
              "address": "0x9876543210987654321098765432109876543210",
              "contenthash": "ipfs://QmYourContentHash"
            }
          ]
        }' \
     https://namestone.com/api/public_v1/set-names

Error Handling

The set-names endpoint provides detailed error information:

Common Error Scenarios

Invalid Names Array

{ "error": "Missing names array or empty array" }

Individual Name Errors

{ "error": "Invalid ens name at index 2: invalid..name" }

Name Limit Exceeded

{
  "error": "Api name limit would be exceeded. Current: 5, Adding: 10, Limit: 12"
}

Transaction Failure

{
  "error": "Batch operation failed",
  "processed": 0,
  "errors": [
    {
      "index": 1,
      "name": "problematic-name",
      "error": "Specific error message"
    }
  ],
  "total": 5
}