### Namestone API Quick Start Example

Source: https://github.com/namestonehq/namestone/blob/main/PLAN-llm-friendly-docs.md

Provides a cURL command for a quick start example, demonstrating how to create a subdomain using the set-name endpoint.

```shell
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '{"domain": "yourbrand.eth", "name": "alice", "address": "0x..."}' \
  https://namestone.com/api/public_v1/mainnet/set-name
```

--------------------------------

### Enable Domain with NameStone SDK

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/enable-domain.mdx

This TypeScript example demonstrates how to use the NameStone SDK to get a SIWE message, sign it, and then enable a domain. It includes error handling for authentication and network issues.

```typescript
import NameStone,
{
  AuthenticationError,
  NetworkError,
} from "@namestone/namestone-sdk";
import { createWalletClient, custom } from "viem"; // if using viem for signing

// Initialize the NameStone instance (no API key needed for initial setup)
const ns = new NameStone();

// Define the parameters
const address = "0xE997d9b785Dd99832d21b3Ce5A34fCacC6D53C57";
const domain = "testbrand.eth";
const email = "your_email@company.com";
const company_name = "Your Company Name";

// Use an immediately invoked async function to allow top-level await
(async () => {
  try {
    // Step 1: Get the SIWE message
    const siweMessage = await ns.getSiweMessage({
      address: address,
    });

    console.log("SIWE message received:", siweMessage);

    // Step 2: Sign the message (example using viem)
    const walletClient = createWalletClient({
      transport: custom(window.ethereum),
    });

    const signature = await walletClient.signMessage({
      message: siweMessage,
    });

    console.log("Message signed:", signature);

    // Step 3: Enable domain with the signed message
    const response = await ns.enableDomain({
      company_name: company_name,
      email: email,
      domain: domain,
      address: address,
      signature: signature,
      // Optional parameters:
      // api_key: "existing_api_key",  // if you want to use an existing key
      // cycle_key: "1"                // if you want to cycle an existing key
    });

    console.log("Domain enabled successfully! New API key:", response.api_key);

    // Step 4: You can now initialize a new NameStone instance with the API key
    const nsWithAuth = new NameStone(response.api_key);

    // Now you can use other endpoints that require authentication...
  } catch (error) {
    if (error instanceof AuthenticationError) {
      console.error("Authentication failed:", error.message);
    } else if (error instanceof NetworkError) {
      console.error("Network error:", error.message);
    } else {
      console.error("An unexpected error occurred:", error);
    }
  }
})();
```

--------------------------------

### Install Namestone SDK

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/sdk-quickstart.mdx

Install the Namestone SDK using npm. This is the first step before initializing the client.

```bash
npm install @namestone/namestone-sdk
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/namestonehq/namestone/blob/main/contribute.md

Install all necessary project dependencies using Yarn.

```bash
yarn install
```

--------------------------------

### Initialize Namestone SDK (TypeScript)

Source: https://github.com/namestonehq/namestone/blob/main/public/llms.txt

Demonstrates how to initialize the Namestone SDK for both mainnet and Sepolia testnet. Ensure you have installed the SDK using 'npm install @namestone/namestone-sdk'.

```typescript
import NameStone from "@namestone/namestone-sdk";

// Mainnet
const ns = new NameStone("YOUR_API_KEY");

// Sepolia testnet
const ns = new NameStone("YOUR_API_KEY", { network: "sepolia" });
```

--------------------------------

### Start Local PostgreSQL Service

Source: https://github.com/namestonehq/namestone/blob/main/contribute.md

Use Homebrew to start the PostgreSQL service on macOS.

```bash
brew services start postgresql
```

--------------------------------

### Run Development Server

Source: https://github.com/namestonehq/namestone/blob/main/contribute.md

Start the development server for the NameStone application.

```bash
yarn dev
```

--------------------------------

### llms.txt Structure Example

Source: https://github.com/namestonehq/namestone/blob/main/PLAN-llm-friendly-docs.md

Defines the hierarchical structure for a plain-text file optimized for LLM consumption, including sections for quick start, authentication, endpoints, and more.

```plaintext
# Namestone API

[One-line description]

## Quick Start
[Minimal working example]

## Authentication
[How to auth]

## Endpoints
[All endpoints with minimal description]

## Common Operations
[Most frequent use cases with examples]

## SDK
[How to use the TypeScript SDK]

## Limits & Constraints
[Important limitations]

## Links
[Where to find more]
```

--------------------------------

### Set Domain using NameStone SDK

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/set-domain.mdx

This TypeScript example demonstrates how to set domain records using the NameStone SDK. It includes error handling for authentication and network issues. Ensure you have installed the SDK and replaced placeholder values.

```typescript
import NameStone, { AuthenticationError, NetworkError, TextRecords } from '@namestone/namestone-sdk';

// Initialize the NameStone instance
const ns = new NameStone(<YOUR_API_KEY_HERE>);

// Define the domain parameters
const domain = "testbrand.eth";
const address = "0xE997d9b785Dd99832d21b3Ce5A34fCacC6D53C57";

// Define the text records
const textRecords: TextRecords = {
  "com.twitter": "namestonehq",
  "com.github": "aslobodnik",
  "com.discord": "superslobo",
  "url": "https://www.namestone.com",
  "location": "📍 nyc",
  "description": "APIs are cool",
  "avatar": "https://raw.githubusercontent.com/aslobodnik/profile/main/pic.jpeg"
};

// Use an immediately invoked async function to allow top-level await
(async () => {
  try {
    const response = await ns.setDomain({domain:domain, address:address, text_records:textRecords});

    console.log("Domain set successfully:", response);
  } catch (error) {
    if (error instanceof AuthenticationError) {
      console.error("Authentication failed:", error.message);
    } else if (error instanceof NetworkError) {
      console.error("Network error:", error.message);
    } else {
      console.error("An unexpected error occurred:", error);
    }
  }
})();
```

--------------------------------

### Verify Node.js and Yarn Installation

Source: https://github.com/namestonehq/namestone/blob/main/contribute.md

Check if Node.js and Yarn are installed and accessible in your environment.

```bash
node --version
yarn --version
```

--------------------------------

### Get SIWE Message with Namestone SDK

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/get-siwe-message.mdx

This TypeScript example demonstrates how to use the Namestone SDK to fetch a SIWE message. It includes optional 'domain' and 'uri' parameters and error handling for network issues.

```typescript
import NameStone, {
  AuthenticationError,
  NetworkError,
} from "@namestone/namestone-sdk";

// Initialize the NameStone instance
const ns = new NameStone();

// Define the SIWE message parameters
const address = "0x57632Ba9A844af0AB7d5cdf98b0056c8d87e3A85";
const domain = "yourdomain.tld"; // optional
const uri = "https://yourdomain.tld/api"; // optional

// Use an immediately invoked async function to allow top-level await
(async () => {
  try {
    const response = await ns.getSiweMessage({
      address: address,
      domain: domain, // optional parameter
      uri: uri, // optional parameter
    });

    console.log("SIWE message received:", response);

    // Example response message will look like:
    // namestone.com wants you to sign in with your Ethereum account:
    // 0x57632Ba9A844af0AB7d5cdf98b0056c8d87e3A85
    // Sign this message to access protected endpoints.
    // URI: https://namestone.com/api/public_v1/get-siwe-message
    // Version: 1
    // Chain ID: 1
    // Nonce: b10ffd444b0a2d810377a3900ba6cd0422141306d158520f24b2805952ea589f9bd1bcbf2e353a14105830183472de5f
    // Issued At: 2024-10-18T17:05:37.933Z
  } catch (error) {
    if (error instanceof NetworkError) {
      console.error("Network error:", error.message);
    } else {
      console.error("An unexpected error occurred:", error);
    }
  }
})();
```

--------------------------------

### Copy Environment File

Source: https://github.com/namestonehq/namestone/blob/main/contribute.md

Create a local .env file by copying the example environment file.

```bash
cp .env.example .env
```

--------------------------------

### Example SIWE Message Return Format

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/get-siwe-message.mdx

This is an example of the SIWE message structure you will receive from the API. It contains all the necessary fields for a user to sign.

```text
Siwe message: namestone.com wants you to sign in with your Ethereum account:
0x57632Ba9A844af0AB7d5cdf98b0056c8d87e3A85

Sign this message to access protected endpoints.

URI: https://namestone.com/api/public_v1/get-siwe-message
Version: 1
Chain ID: 1
Nonce: b10ffd444b0a2d810377a3900ba6cd0422141306d158520f24b2805952ea589f9bd1bcbf2e353a14105830183472de5f
Issued At: 2024-10-18T17:05:37.933Z
```

--------------------------------

### Example API Return Structure

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/get-names.mdx

This is an example of the JSON response structure when successfully retrieving name data, including associated text records and coin types.

```json
[
   {
      "name":"namestone",
      "address":"0x57632Ba9A844af0AB7d5cdf98b0056c8d87e3A85",
      "domain":"testbrand.eth",
      "text_records":{
         "avatar":"https://imagedelivery.net/UJ5oN2ajUBrk2SVxlns2Aw/71cec612-fe0b-46a4-3d1c-e3eaf53d4600/public",
         "com.twitter":"namestonehq",
         "com.discord":"superslobo",
         "location":"📍 nyc",
         "url":"https://namestone.com",
         "description":"Brand Choice"
      }
      "coin_types": {
         "2147483785": "0x534631Bcf33BDb069fB20A93d2fdb9e4D4dD42CF",
         "2147492101": "0x534631Bcf33BDb069fB20A93d2fdb9e4D4dD42CF",
         "2147525809": "0x534631Bcf33BDb069fB20A93d2fdb9e4D4dD42CF",
         "2147483658": "0x534631Bcf33BDb069fB20A93d2fdb9e4D4dD42CF"
      },
   }
]
```

--------------------------------

### Setup and Initialization for ENS Resolution

Source: https://github.com/namestonehq/namestone/blob/main/public/lens.html

Initializes ethers.js provider and retrieves the ENS name from the URL or defaults to 'raffy.eth'. Sets up the resolver and contract instances for interacting with ENS.

```javascript
import { ethers } from 'ethers';
import { Profile, Record, Coin } from '@namestone/enson';

const provider = new ethers.JsonRpcProvider('https://eth.drpc.org', 1, {
  staticNetwork: true,
  batchMaxCount: 5
});

const name = window.location.search.includes('name=') ? new URLSearchParams(window.location.search).get('name') : 'raffy.eth';

const resolver = await provider.getResolver(name);
const contract = new ethers.Contract(resolver.address, [
  'function resolve(bytes, bytes) view returns (bytes)',
  'function supportsInterface(bytes4) view returns (bool)',
], provider);

const multi_abi = new ethers.Interface([
  'function multicall(bytes[]) view returns (bytes[])'
]);

const [extended, onchain] = await Promise.all([
  contract.supportsInterface('0x9061b923'), //contract.supportsInterface('0x73302a25'),
  contract.supportsInterface('0x727cc20d'), // onchain(bytes32)
]);

console.log({ extended, onchain });
```

--------------------------------

### Run PostgreSQL Docker Container

Source: https://github.com/namestonehq/namestone/blob/main/contribute.md

Start a PostgreSQL container named 'namestone-postgres' with a password and run it in detached mode.

```bash
docker run --name namestone-postgres -e POSTGRES_PASSWORD=namestone -d postgres
```

--------------------------------

### Create Subdomain with Profile Data using cURL

Source: https://github.com/namestonehq/namestone/blob/main/public/llms.txt

This cURL example demonstrates creating a subdomain and including additional profile data such as avatar and social media handles in the text records.

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '{
    "domain": "brand.eth",
    "name": "alice",
    "address": "0x1234...",
    "text_records": {
      "avatar": "https://example.com/pic.jpg",
      "com.twitter": "alice",
      "description": "Alice profile"
    }
  }' \
  https://namestone.com/api/public_v1/set-name
```

--------------------------------

### Fetch Domain Records with Namestone SDK

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/get-domain.mdx

This TypeScript example demonstrates how to use the Namestone SDK to fetch domain records. It includes error handling for authentication and network issues. Initialize the SDK with your API key.

```typescript
import NameStone, { AuthenticationError, NetworkError, DomainData } from '@namestone/namestone-sdk';

// Initialize the NameStone instance
const ns = new NameStone(<YOUR_API_KEY_HERE>);

// Define the domain to query
const domain = "testbrand.eth";

// Use an immediately invoked async function to allow top-level await
(async () => {
  try {
    const response: DomainData[] = await ns.getDomain({domain:domain});
    console.log(response);
  } catch (error) {
    if (error instanceof AuthenticationError) {
      console.error("Authentication failed:", error.message);
    } else if (error instanceof NetworkError) {
      console.error("Network error:", error.message);
    } else {
      console.error("An unexpected error occurred:", error);
    }
  }
})();
```

--------------------------------

### Fetch Names using NameStone SDK

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/get-names.mdx

This TypeScript example demonstrates how to use the NameStone SDK to fetch names for a given domain and address. It includes error handling for authentication and network issues.

```typescript
import NameStone, { AuthenticationError, NetworkError, NameData } from '@namestone/namestone-sdk';

// Initialize the NameStone instance
const ns = new NameStone(<YOUR_API_KEY_HERE>);

// Define the query parameters
const domain = "testbrand.eth";
const address = "0x57632Ba9A844af0AB7d5cdf98b0056c8d87e3A85";

// Use an immediately invoked async function to allow top-level await
(async () => {
  try {
    const response: NameData[] = await ns.getNames({domain:domain, address:address});

    if (response.length > 0) {
      console.log(`Found ${response.length} name(s):`);
      response.forEach((nameData, index) => {
        console.log(`
Name ${index + 1}:`);
        console.log(JSON.stringify(nameData, null, 2));
      });
    } else {
      console.log("No names found for the specified domain and address.");
    }
  } catch (error) {
    if (error instanceof AuthenticationError) {
      console.error("Authentication failed:", error.message);
    } else if (error instanceof NetworkError) {
      console.error("Network error:", error.message);
    } else {
      console.error("An unexpected error occurred:", error);
    }
  }
})();
```

--------------------------------

### OpenAPI Simple Error Response Example

Source: https://github.com/namestonehq/namestone/blob/main/PLAN-llm-friendly-docs.md

Provides an example of a simple error response format for API requests, containing a single 'error' field with a descriptive message.

```json
{"error": "Invalid domain"}
```

--------------------------------

### robots.txt for LLM-friendly Documentation

Source: https://github.com/namestonehq/namestone/blob/main/PLAN-llm-friendly-docs.md

Add this content to your public/robots.txt file to guide web crawlers and LLMs.

```Text
User-agent: *
Allow: /

# LLM-friendly documentation
# See: https://namestone.com/llms.txt
```

--------------------------------

### Create Index on Domain ID

Source: https://github.com/namestonehq/namestone/blob/main/lib/sql_commands.txt

Example of creating an index on the 'domain_id' column in the 'domain_text_record' table. This can improve query performance for lookups involving this column.

```sql
create index domain_text_record__domain_id on domain_text_record(domain_id);
```

--------------------------------

### GET /get-domain

Source: https://github.com/namestonehq/namestone/blob/main/public/llms.txt

Retrieves the configuration details for a specific main ENS domain.

```APIDOC
## GET /get-domain

### Description
Retrieves the configuration details for a specific main ENS domain.

### Method
GET

### Endpoint
/api/public_v1/{endpoint} or /api/public_v1_sepolia/{endpoint}

### Parameters
#### Query Parameters
- **domain** (string) - Required - The main ENS domain to retrieve details for (e.g., "brand.eth").

### Request Example
```
https://namestone.com/api/public_v1/get-domain?domain=brand.eth
```

### Response
#### Success Response (200)
- Returns an object with domain configuration details:
  - **domain** (string) - The main ENS domain.
  - **address** (string) - The associated Ethereum address.
  - **text_records** (object) - Key-value pairs for text records.
  - **coin_types** (object) - Key-value pairs for L2 addresses.

#### Response Example
```json
{
  "domain": "brand.eth",
  "address": "0x1234...",
  "text_records": {"website": "https://brand.com"},
  "coin_types": {}
}
```
```

--------------------------------

### Search Names using Namestone SDK

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/search-names.mdx

This TypeScript example demonstrates how to use the Namestone SDK to search for names within a domain. It includes error handling for authentication and network issues, and logs the results or a 'not found' message.

```typescript
import NameStone, { AuthenticationError, NetworkError, NameData } from '@namestone/namestone-sdk';

// Initialize the NameStone instance
const ns = new NameStone(<YOUR_API_KEY_HERE>);

// Define the search parameters
const domain = "example.xyz";
const name = "ro";

// Use an immediately invoked async function to allow top-level await
(async () => {
  try {
    const response: NameData[] = await ns.searchNames({domain:domain, name:name});

    if (response.length > 0) {
      console.log(`Found ${response.length} name(s) matching the search criteria:`);
      response.forEach((nameData, index) => {
        console.log(`
Result ${index + 1}:`);
        console.log(JSON.stringify(nameData, null, 2));
      });
    } else {
      console.log(`No names found matching '${name}' in the domain '${domain}'.`);
    }
  } catch (error) {
    if (error instanceof AuthenticationError) {
      console.error("Authentication failed:", error.message);
    } else if (error instanceof NetworkError) {
      console.error("Network error:", error.message);
    } else {
      console.error("An unexpected error occurred:", error);
    }
  }
})();
```

--------------------------------

### Get Names using SDK

Source: https://github.com/namestonehq/namestone/blob/main/PLAN-llm-friendly-docs.md

Retrieve a list of names associated with a domain using the SDK.

```TypeScript
const names = await ns.getNames({ domain: "yourbrand.eth" });
```

--------------------------------

### Success Response Example

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/set-names.mdx

This JSON structure represents a successful batch operation, indicating the number of processed names and individual results.

```json
{
  "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
    }
  ]
}
```

--------------------------------

### Search Names

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/search-names.mdx

Fetches all names (subdomains) for a domain that start with a specified string. Results are ordered alphabetically.

```APIDOC
## GET /search-names

### Description
Fetches all names (subdomains) for a domain that start with a specified string. Results are ordered alphabetically.

### Method
GET

### Endpoint
/search-names

### Parameters
#### Query Parameters
- **domain** (string) - Required - The domain (e.g. "testbrand.eth").
- **name** (string) - Required - The string names will start with. For example, 'ro' will return 'rob', 'robert', etc.
- **text_records** (1 or 0) - Optional - Whether or not the route returns text records. 1 by default.
- **limit** (integer) - Optional - Number of names returned in request. Default 50.
- **exact_match** (1 or 0) - Optional - Route will only return names that are an exact match.
- **offset** (integer) - Optional - Offset the returned names window. Default 0.

### Request Example
```
https://namestone.com/api/public_v1/search-names?domain=example.xyz&name=ro
```

### Response
#### Success Response (200)
- **name** (string) - The name of the subdomain.
- **address** (string) - The associated address.
- **domain** (string) - The domain the subdomain belongs to.
- **textRecords** (object) - An object containing associated text records.

#### Response Example
```json
[
   {
      "name":"robert",
      "address":"0x57632Ba9A844af0AB7d5cdf98b0056c8d87e3A85",
      "domain":"testbrand.eth",
      "textRecords":{
         "avatar":"https://imagedelivery.net/UJ5oN2ajUBrk2SVxlns2Aw/71cec612-fe0b-46a4-3d1c-e3eaf53d4600/public",
         "com.twitter":"namestonehq",
         "com.discord":"superslobo",
         "location":"📍 nyc",
         "url":"https://namestone.com",
         "description":"Brand Choice"
      }
   }
]
```
```

--------------------------------

### Get SIWE Message for Domain Enablement

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/api-routes.mdx

Retrieve a signable SIWE (Sign-In with Ethereum) message required for protected routes like enable-domain. You will need to sign this message with your Ethereum wallet.

```bash
curl -X GET https://namestone.com/api/get-siwe-message?domain=example.com \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Test API Endpoint Locally

Source: https://github.com/namestonehq/namestone/blob/main/contribute.md

Make a GET request to a local API endpoint to retrieve names, using an authorization header with a test API key.

```bash
curl -X GET "http://localhost:3000/api/public_v1/get-names?domain=test-mainnet.eth" \
  -H "Authorization: test-api-key-mainnet"
```

--------------------------------

### cURL Example for Set Names (Batch)

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/set-names.mdx

This cURL command demonstrates how to use the Set Names (Batch) API to create or update multiple names with addresses, text records, and L2 coin types.

```bash
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 Response Example

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/set-names.mdx

This JSON structure illustrates an error response for a batch operation, detailing the overall failure and specific errors encountered for individual names.

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

--------------------------------

### OpenAPI Batch Error Response Example

Source: https://github.com/namestonehq/namestone/blob/main/PLAN-llm-friendly-docs.md

Illustrates the structure of a batch error response, including details about processed items, specific errors with indices, and the total number of items.

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

--------------------------------

### Example API Return for Search Names

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/search-names.mdx

This is a sample JSON response from the search-names API endpoint, showing a list of name objects, each containing the name, address, domain, and associated text records.

```json
[
   {
      "name":"robert",
      "address":"0x57632Ba9A844af0AB7d5cdf98b0056c8d87e3A85",
      "domain":"testbrand.eth",
      "textRecords":{
         "avatar":"https://imagedelivery.net/UJ5oN2ajUBrk2SVxlns2Aw/71cec612-fe0b-46a4-3d1c-e3eaf53d4600/public",
         "com.twitter":"namestonehq",
         "com.discord":"superslobo",
         "location":"📍 nyc",
         "url":"https://namestone.com",
         "description":"Brand Choice"
      }
   }
]
```

--------------------------------

### Example Domain Response

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/get-domains.mdx

This JSON structure represents a successful response, detailing a domain's properties including its address, contenthash, associated text records, and coin types.

```json
[
  {
    "domain": "namestone.xyz",
    "address": "0x534631Bcf33BDb069fB20A93d2fdb9e4D4dD42CF",
    "contenthash": "ipfs://QmUbTVz1L4uEvAPg5QcSu8Rifq2CtTc4SYmasXLAYkFQbp",
    "text_records": {
      "com.twitter": "namestonehq",
      "com.github": "resolverworks",
      "url": "https://www.namestone.xyz",
      "description": "Namestone ENS Resolver"
    },
    "coin_types": {
      "60": "0x534631Bcf33BDb069fB20A93d2fdb9e4D4dD42CF",
      "2147483785": "0x534631Bcf33BDb069fB20A93d2fdb9e4D4dD42CF"
    }
  },
  {
    "domain": "example.eth",
    "address": "0xA47632346786AD59c8590Bd4898D84B4eAB97644",
    "contenthash": null,
    "text_records": {
      "description": "Example domain"
    },
    "coin_types": {}
  }
]
```

--------------------------------

### OpenAPI Parameter Schema for Boolean-ish Values

Source: https://github.com/namestonehq/namestone/blob/main/PLAN-llm-friendly-docs.md

Documents how boolean-like parameters (0 or 1) should be represented in the OpenAPI spec. This example shows the schema for 'text_records' parameter.

```yaml
text_records:
  type: integer
  enum: [0, 1]
  default: 1
  description: Whether to return text records. 1 = yes, 0 = no.
```

--------------------------------

### OpenAPI Server Variable Example

Source: https://github.com/namestonehq/namestone/blob/main/PLAN-llm-friendly-docs.md

Defines server variables for handling different networks (mainnet, sepolia) within the OpenAPI specification. This approach keeps the specification DRY by using a single path with a network variable.

```yaml
servers:
  - url: https://namestone.com/api/public_v1/{network}
    variables:
      network:
        default: mainnet
        enum: [mainnet, sepolia]
        description: Ethereum network
```

--------------------------------

### Search Names using cURL

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/search-names.mdx

Use this cURL command to make a GET request to the search-names endpoint. Ensure you replace 'YOUR_API_KEY' with your actual API key and adjust the 'domain' and 'name' parameters as needed.

```bash
curl -X GET \
     -H 'Authorization: YOUR_API_KEY' \
     'https://namestone.com/api/public_v1/search-names?domain=example.xyz&name=ro'
```

--------------------------------

### Search Subdomains Autocomplete using cURL

Source: https://github.com/namestonehq/namestone/blob/main/public/llms.txt

Perform an autocomplete search for subdomains within a given domain. This example shows how to find names starting with a specific prefix.

```bash
curl "https://namestone.com/api/public_v1/search-names?domain=brand.eth&name=ali"
```

--------------------------------

### Get Domain

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/get-domain.mdx

Fetches the current text records set for a domain. This is a GET request that requires the domain name as a query parameter.

```APIDOC
## GET /api/public_v1/get-domain

### Description
Fetches the current text records set for a domain.

### Method
GET

### Endpoint
/api/public_v1/get-domain

### Parameters
#### Query Parameters
- **domain** (string) - Required - The domain (e.g. "testbrand.eth").

### Request Example
```bash
curl -X GET \
     -H 'Authorization: YOUR_API_KEY' \
     'https://namestone.com/api/public_v1/get-domain?domain=testbrand.eth'
```

### Response
#### Success Response (200)
- **domain** (string) - The queried domain name.
- **address** (string) - The blockchain address associated with the domain.
- **text_records** (object) - An object containing various text records for the domain (e.g., avatar, com.twitter, location, description).
- **coin_types** (object) - An object mapping coin type identifiers to blockchain addresses for multichain support.

#### Response Example
```json
[
   {
      "domain":"testbrand.eth",
      "address":"0x57632Ba9A844af0AB7d5cdf98b0056c8d87e3A85",
      "text_records":{
         "avatar":"https://imagedelivery.net/UJ5oN2ajUBrk2SVxlns2Aw/71cec612-fe0b-46a4-3d1c-e3eaf53d4600/public",
         "com.twitter":"namestonehq",
         "com.discord":"superslobo",
         "location":"📍 nyc",
         "url":"https://namestone.com",
         "description":"Brand Choice"
      },
      "coin_types": {
         "2147483785": "0x534631Bcf33BDb069fB20A93d2fdb9e4D4dD42CF",
         "2147492101": "0x534631Bcf33BDb069fB20A93d2fdb9e4D4dD42CF",
         "2147525809": "0x534631Bcf33BDb069fB20A93d2fdb9e4D4dD42CF",
         "2147483658": "0x534631Bcf33BDb069fB20A93d2fdb9e4D4dD42CF"
      }
   }
]
```
```

--------------------------------

### Push Database Migrations

Source: https://github.com/namestonehq/namestone/blob/main/contribute.md

Apply database migrations to your database using Prisma.

```bash
npx prisma db push
```

--------------------------------

### get-domain

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/api-routes.mdx

Get text records and address for a given domain.

```APIDOC
## GET /get-domain

### Description
Get text records and address for a given domain.

### Method
GET

### Endpoint
/get-domain

### Parameters
#### Query Parameters
- **domain** (string) - Required - The domain to query.

### Response
#### Success Response (200)
- **address** (string) - The address associated with the domain.
- **records** (object) - Text records for the domain.

#### Response Example
{
  "address": "0x123...",
  "records": {"website": "https://example.com"}
}
```

--------------------------------

### Get Domain

Source: https://github.com/namestonehq/namestone/blob/main/PLAN-llm-friendly-docs.md

Retrieves information for a specific domain. Authentication is optional.

```APIDOC
## GET /get-domain

### Description
Retrieves information for a specific domain. Authentication is optional.

### Method
GET

### Endpoint
/api/public_v1/{network}/get-domain

### Parameters
#### Path Parameters
- **network** (string) - Required - The Ethereum network (e.g., mainnet, sepolia).

#### Query Parameters
- **domain** (string) - Required - The domain to retrieve information for.

### Response
#### Success Response (200)
- **domain** (string) - The domain name.
- **address** (string) - The primary address associated with the domain.
- **contenthash** (string) - The content hash (IPFS or IPNS).
- **text_records** (object) - ENS text records associated with the domain.
- **coin_types** (object) - Multi-chain addresses associated with the domain.

#### Response Example
```json
{
  "domain": "example.com",
  "address": "0x123...",
  "contenthash": "ipfs://QmYourContentHash",
  "text_records": {
    "avatar": "https://example.com/avatar.png"
  },
  "coin_types": {
    "2147483785": "0x..."
  }
}
```
```

--------------------------------

### Get Names

Source: https://github.com/namestonehq/namestone/blob/main/PLAN-llm-friendly-docs.md

Retrieves names associated with a domain or address. Authentication is optional.

```APIDOC
## GET /get-names

### Description
Retrieves names associated with a domain or address. If no domain or address is provided, it returns all subnames for all domains tied to the API key. Authentication is optional.

### Method
GET

### Endpoint
/api/public_v1/{network}/get-names

### Parameters
#### Path Parameters
- **network** (string) - Required - The Ethereum network (e.g., mainnet, sepolia).

#### Query Parameters
- **domain** (string) - Optional - The domain to filter names by.
- **address** (string) - Optional - The address to filter names by.
- **text_records** (integer) - Optional - Whether to return text records. 1 = yes, 0 = no. Defaults to 1.

### Response
#### Success Response (200)
- **names** (array) - An array of name objects.
  - **name** (string) - The name.
  - **domain** (string) - The domain.
  - **address** (string) - The associated address.
  - **text_records** (object) - ENS text records (if requested).
  - **coin_types** (object) - Multi-chain addresses.

#### Response Example
```json
{
  "names": [
    {
      "name": "mynamesub",
      "domain": "example.com",
      "address": "0x123...",
      "text_records": {
        "avatar": "https://example.com/avatar.png"
      },
      "coin_types": {
        "2147483785": "0x..."
      }
    }
  ]
}
```
```

--------------------------------

### Get Domains

Source: https://github.com/namestonehq/namestone/blob/main/PLAN-llm-friendly-docs.md

Retrieves a list of all domains associated with the API key. No authentication required.

```APIDOC
## GET /get-domains

### Description
Retrieves a list of all domains associated with the API key. No authentication is required for this endpoint.

### Method
GET

### Endpoint
/api/public_v1/{network}/get-domains

### Parameters
#### Path Parameters
- **network** (string) - Required - The Ethereum network (e.g., mainnet, sepolia).

### Response
#### Success Response (200)
- **domains** (array) - An array of domain objects.
  - **domain** (string) - The domain name.
  - **address** (string) - The primary address.
  - **contenthash** (string) - The content hash.
  - **text_records** (object) - ENS text records.
  - **coin_types** (object) - Multi-chain addresses.

#### Response Example
```json
{
  "domains": [
    {
      "domain": "example.com",
      "address": "0x123...",
      "contenthash": "ipfs://QmYourContentHash",
      "text_records": {
        "avatar": "https://example.com/avatar.png"
      },
      "coin_types": {
        "2147483785": "0x..."
      }
    },
    {
      "domain": "anotherdomain.org",
      "address": "0x456...",
      "contenthash": null,
      "text_records": {},
      "coin_types": {}
    }
  ]
}
```
```

--------------------------------

### enable-domain

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/api-routes.mdx

Enable your domain on namestone. Requires a signed message from get-siwe-message.

```APIDOC
## POST /enable-domain

### Description
Enable your domain on namestone. Requires a signed message from the `get-siwe-message` endpoint.

### Method
POST

### Endpoint
/enable-domain

### Parameters
#### Request Body
- **domain** (string) - Required - The domain to enable.
- **signedMessage** (string) - Required - The signed message obtained from `get-siwe-message`.

### Request Example
{
  "domain": "example.com",
  "signedMessage": "0x..."
}

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
{
  "message": "Domain enabled successfully."
}
```

--------------------------------

### get-siwe-message

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/api-routes.mdx

Get a signable siwe message for accessing protected routes like enable-domain.

```APIDOC
## GET /get-siwe-message

### Description
Get a signable SIWE (Sign-In with Ethereum) message for accessing protected routes like `enable-domain`.

### Method
GET

### Endpoint
/get-siwe-message

### Parameters
#### Query Parameters
- **address** (string) - Required - The Ethereum address for which to generate the SIWE message.

### Response
#### Success Response (200)
- **message** (string) - The SIWE message to be signed by the user.

#### Response Example
{
  "message": "<siwe_message_string>"
}
```

--------------------------------

### Enable Domain via Curl

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/enable-domain.mdx

Use this cURL command to enable a domain by sending a POST request with domain details and a signed SIWE message.

```bash
curl -X POST \
     -H 'Content-Type: application/json' \
     -d '{
       "company_name": "your_company_name",
       "email": "your_email@company.com",
       "domain":"testbrand.eth",
       "address":"0xE997d9b785Dd99832d21b3Ce5A34fCacC6D53C57",
       "signature": "signed_siwe_message"
        }' \
     https://namestone.com/api/public_v1/enable-domain
```

--------------------------------

### Get SIWE Message

Source: https://github.com/namestonehq/namestone/blob/main/PLAN-llm-friendly-docs.md

Retrieves a SIWE (Sign-In with Ethereum) message for authentication. No authentication required.

```APIDOC
## GET /get-siwe-message

### Description
Retrieves a SIWE (Sign-In with Ethereum) message for authentication. No authentication is required for this endpoint.

### Method
GET

### Endpoint
/api/public_v1/{network}/get-siwe-message

### Parameters
#### Path Parameters
- **network** (string) - Required - The Ethereum network (e.g., mainnet, sepolia).

### Response
#### Success Response (200)
- **message** (string) - The SIWE message to be signed.

#### Response Example
```json
{
  "message": "Welcome to Namestone! Sign in with Ethereum to continue. Nonce: abc123xyz"
}
```
```

--------------------------------

### Seed the Database

Source: https://github.com/namestonehq/namestone/blob/main/contribute.md

Populate the database with test data using the provided seed script.

```bash
node ./prisma/seed.js
```

--------------------------------

### GET /get-domains

Source: https://github.com/namestonehq/namestone/blob/main/public/llms.txt

Retrieves a list of all main ENS domains managed by a specific admin address.

```APIDOC
## GET /get-domains

### Description
Retrieves a list of all main ENS domains managed by a specific admin address.

### Method
GET

### Endpoint
/api/public_v1/{endpoint} or /api/public_v1_sepolia/{endpoint}

### Parameters
#### Query Parameters
- **admin-address** (string) - Required - The Ethereum address of the administrator to list domains for.

### Request Example
```
https://namestone.com/api/public_v1/get-domains?admin-address=0x1234...
```

### Response
#### Success Response (200)
- Returns an array of domain objects. Each object may contain:
  - **domain** (string) - The main ENS domain.
  - **address** (string) - The associated Ethereum address.
  - **text_records** (object) - Key-value pairs for text records.
  - **coin_types** (object) - Key-value pairs for L2 addresses.

#### Response Example
```json
[
  {
    "domain": "brand.eth",
    "address": "0x1234...",
    "text_records": {},
    "coin_types": {}
  }
]
```
```

--------------------------------

### Enable Domain Programmatically

Source: https://github.com/namestonehq/namestone/blob/main/data/docs/api-routes.mdx

Use the enable-domain endpoint to programmatically enable your domain on NameStone. This requires a signed message obtained from the get-siwe-message endpoint.

```bash
curl -X POST https://namestone.com/api/enable-domain \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"domain": "example.com", "signature": "YOUR_SIWE_SIGNATURE"}'
```

--------------------------------

### Run Project Tests

Source: https://github.com/namestonehq/namestone/blob/main/contribute.md

Execute all project tests using the Yarn test command.

```bash
yarn test
```

--------------------------------

### GET /search-names

Source: https://github.com/namestonehq/namestone/blob/main/public/llms.txt

Searches for ENS subdomains based on a domain and a name prefix. Useful for autocomplete functionality.

```APIDOC
## GET /search-names

### Description
Searches for ENS subdomains based on a domain and a name prefix. Useful for autocomplete functionality.

### Method
GET

### Endpoint
/api/public_v1/{endpoint} or /api/public_v1_sepolia/{endpoint}

### Parameters
#### Query Parameters
- **domain** (string) - Required - The main ENS domain to search within (e.g., "brand.eth").
- **name** (string) - Required - The prefix or name to search for (e.g., "ali").
- **exact_match** (integer) - Optional - Set to 1 for an exact match, 0 for prefix matching (default: 0).
- **limit** (integer) - Optional - The maximum number of results to return (default: 50).

### Request Example
```
https://namestone.com/api/public_v1/search-names?domain=brand.eth&name=ali
```

### Response
#### Success Response (200)
- Returns an array of subdomain objects matching the search criteria. Each object may contain:
  - **name** (string) - The subdomain name.
  - **domain** (string) - The main ENS domain.
  - **address** (string) - The associated Ethereum address.
  - **text_records** (object) - Optional - Key-value pairs for text records.
  - **coin_types** (object) - Optional - Key-value pairs for L2 addresses.

#### Response Example
```json
[
  {
    "name": "alice",
    "domain": "brand.eth",
    "address": "0x1234..."
  }
]
```
```

--------------------------------

### GET /get-names

Source: https://github.com/namestonehq/namestone/blob/main/public/llms.txt

Retrieves a list of ENS subdomains associated with a specific domain or address. Supports pagination.

```APIDOC
## GET /get-names

### Description
Retrieves a list of ENS subdomains associated with a specific domain or address. Supports pagination.

### Method
GET

### Endpoint
/api/public_v1/{endpoint} or /api/public_v1_sepolia/{endpoint}

### Parameters
#### Query Parameters
- **domain** (string) - Optional - The main ENS domain to filter by (e.g., "brand.eth").
- **address** (string) - Optional - The Ethereum address to filter by.
- **limit** (integer) - Optional - The maximum number of results to return (default: 50).
- **offset** (integer) - Optional - The number of results to skip for pagination.

### Request Example
```
https://namestone.com/api/public_v1/get-names?domain=brand.eth&address=0x1234...
```

### Response
#### Success Response (200)
- Returns an array of subdomain objects. Each object may contain:
  - **name** (string) - The subdomain name.
  - **domain** (string) - The main ENS domain.
  - **address** (string) - The associated Ethereum address.
  - **text_records** (object) - Optional - Key-value pairs for text records.
  - **coin_types** (object) - Optional - Key-value pairs for L2 addresses.

#### Response Example
```json
[
  {
    "name": "alice",
    "domain": "brand.eth",
    "address": "0x1234...",
    "text_records": {"avatar": "...", "com.twitter": "alice"}
  }
]
```
```