AllDomains Monad API Documentation

This document provides client-side usage details for three API endpoints related to domain querying for AllDomains on the Monad Testnet network. Each endpoint is a GET request, designed to retrieve domain-related information. Below, you'll find detailed descriptions, parameters, response formats, and examples for each endpoint, formatted for clarity and ease of use.

Endpoints

1. Get Domain Owner

URL: https://monad.alldomains.id/api/domain-owner/[domain]
Method: GET
Description: Retrieves the owner address of a specified domain.
Path Parameters:
- domain: The domain name to query (e.g., "example.mon"). Required.
Response:
- HTTP Status: 200 (Note: The API always returns a 200 status code; check the "status" field in the response body to determine success or failure.)
- Body:
  - On Success:
```
{
  "status": "success",
  "error": null,
  "msg": null,
  "owner": "0x1234567890abcdef..."
}
```
    - owner: The address owning the domain.
  - On Error:
```
{
  "status": "error",
  "error": "Error message",
  "msg": "Detailed message",
  "owner": null
}
```
    - Possible error scenarios:
      - "Domain is missing": When no domain is provided in the URL.
      - "Domain does not exist": When the domain has no registered owner or is invalid.
      - "RPC Error": When there's an issue communicating with the blockchain network.

Example:

Request: GET /api/domain-owner/example.mon

Response:

{
  "status": "success",
  "error": null,
  "msg": null,
  "owner": "0x1234567890abcdef"
}

2. Get User Domains

URL: https://monad.alldomains.id/api/get-user-domains/[address]
Method: GET
Description: Retrieves a list of all domains owned by a specified address.
Path Parameters:
- address: The user's address to query (e.g., "0x1234567890abcdef"). Required.
Response:
- On Success:
  - HTTP Status: 200
  - Body: An array of domain names owned by the address.
```
[
  {"domain_name":"miester","expires_at":"1772642702","tld":".mon"}
]
```
- On Error:
  - HTTP Status: 500 (or another error code if specified by the underlying error)
  - Body:
```
{
  "msg": "Error message"
}
```
    - The error message varies based on the issue (e.g., network failure, invalid address).

Example:

Request: GET /api/get-user-domains/0x1234567890abcdef

Response:

[{"created_at":"0","domain_name":"miester","expires_at":"1772642702","main_domain_address":"","tld":".mon","transferrable":false}]

3. Get Main Domain

URL: https://monad.alldomains.id/api/main-domain/[address]
Method: GET
Description: Retrieves the main domain associated with a specified public key (address).
Path Parameters:
- address: The user's address (e.g., "0x1234567890abcdef"). Required.
Response:
- HTTP Status: 200 (Note: The API always returns a 200 status code; check the "status" field in the response body to determine success or failure.)
- Body:
  - On Success:
```
{
  "status": "success",
  "error": null,
  "msg": null,
  "mainDomain": "example.mon"
}
```
    - mainDomain: The primary domain linked to the address.
  - On Error:
```
{
  "status": "error",
  "error": "Error message",
  "msg": "Detailed message",
  "mainDomain": null
}
```
    - Possible error scenarios:
      - "address is missing": When no address is provided in the URL.
      - "Main Domain does not exist": When the address has no main domain assigned or an error occurs during retrieval.

Example:

Request: GET /api/main-domain/0x1234567890abcdef

Response:

{
  "status": "success",
  "error": null,
  "msg": null,
  "mainDomain": "example.mon"
}

Additional Notes

CORS Support: All endpoints support cross-origin requests, with appropriate CORS headers (Access-Control-Allow-Origin: *, etc.) included in responses.
Status Codes:
- For /api/domain-owner/[domain] and /api/main-domain/[address], the HTTP status is always 200. Clients must inspect the "status" field ("success" or "error") in the JSON response to determine the outcome.
- For /api/get-user-domains/[address], success returns a 200 status with an array, while errors return a 500 (or other code) with an error object.

Sample code

// Type definitions for API responses

/** Response type for the domain owner endpoint */
interface DomainOwnerResponse {
  status: "success" | "error";
  error: string | null;
  msg: string | null;
  owner: string | null;
}

/** Response type for the main domain endpoint */
interface MainDomainResponse {
  status: "success" | "error";
  error: string | null;
  msg: string | null;
  mainDomain: string | null;
}

/** Response type for the main domain endpoint */
interface UserNft = {
  tld: string;
  expires_at: string;
  domain_name: string;
};

/** Response type for the user domains endpoint */
type UserDomainsResponse = UserNft[]

/**
 * Fetches the owner of a specified domain.
 * @param domain The domain name to query (e.g., "example.mon").
 * @returns A promise that resolves to the DomainOwnerResponse.
 */
async function getDomainOwner(domain: string): Promise<DomainOwnerResponse> {
  const url = `https://monad.alldomains.id/api/domain-owner/${domain}`;
  try {
    const response = await fetch(url);
    const data: DomainOwnerResponse = await response.json();
    return data;
  } catch (error) {
    console.error("Error fetching domain owner:", error);
    return {
      status: "error",
      error: "Failed to fetch domain owner",
      msg: error instanceof Error ? error.message : "Unknown error",
      owner: null,
    };
  }
}

/**
 * Fetches all domains owned by a specified address.
 * @param address The user's address to query (e.g., "0x1234567890abcdef").
 * @returns A promise that resolves to an array of domain names or an error object.
 */
async function getUserDomains(address: string): Promise<UserDomainsResponse> {
  const url = `https://monad.alldomains.id/api/get-user-domains/${address}`;
  try {
    const response = await fetch(url);
    if (response.ok) {
      const data: UserDomainsResponse = await response.json();
      return data;
    } else {
      const errorData: { msg: string } = await response.json();
      return errorData;
    }
  } catch (error) {
    console.error("Error fetching user domains:", error);
    return { msg: "Failed to fetch user domains" };
  }
}

/**
 * Fetches the main domain associated with a specified public key (address).
 * @param pubkey The user's public key or address (e.g., "0x1234567890abcdef").
 * @returns A promise that resolves to the MainDomainResponse.
 */
async function getMainDomain(address: string): Promise<MainDomainResponse> {
  const url = `https://monad.alldomains.id/api/main-domain/${address}`;
  try {
    const response = await fetch(url);
    const data: MainDomainResponse = await response.json();
    return data;
  } catch (error) {
    console.error("Error fetching main domain:", error);
    return {
      status: "error",
      error: "Failed to fetch main domain",
      msg: error instanceof Error ? error.message : "Unknown error",
      mainDomain: null,
    };
  }
}

// Example usage of the functions
async function exampleUsage() {
  // Get domain owner
  const domainOwner = await getDomainOwner("example.mon");
  if (domainOwner.status === "success") {
    console.log("Owner:", domainOwner.owner);
  } else {
    console.error("Error:", domainOwner.error);
  }

  // Get user domains
  const userDomains = await getUserDomains("0x1234567890abcdef");
  if (Array.isArray(userDomains)) {
    console.log("Domains:", userDomains);
  } else {
    console.error("Error:", userDomains.msg);
  }

  // Get main domain
  const mainDomain = await getMainDomain("0x1234567890abcdef");
  if (mainDomain.status === "success") {
    console.log("Main Domain:", mainDomain.mainDomain);
  } else {
    console.error("Error:", mainDomain.error);
  }
}

crypt0miester/alldomains-monad-api.md

AllDomains Monad API Documentation

Endpoints

1. Get Domain Owner

2. Get User Domains

3. Get Main Domain

Additional Notes

Sample code