<project title="Sherlock Domains" summary="The first domain registrar for AI Agents that enables searching, buying, and managing domains with just two lines of code.">Sherlock is a domain registrar built specifically for AI agents, enabling them to search, buy and manage domains programmatically. This web interface provides a human-friendly way to interact with the Sherlock platform.

The web interface provides:
- Domain search and registration
- DNS management 
- Profile settings
- API key management<documentation><doc title="API Documentation"># Sherlock Domains API

Sherlock Domains is a comprehensive domain management API that enables programmatic control over domain registration and DNS management. The API provides capabilities for:

- Domain Operations:
  - Searching for available domain names
  - Purchasing new domains
  - Retrieving domain information and status
  - Managing domain renewals and settings

- DNS Management:
  - Creating, reading, updating, and deleting DNS records
  - Supporting multiple record types (A, CNAME, MX, etc.)
  - Bulk operations for DNS records

The API supports multiple authentication methods:
- JWT Bearer tokens
- Challenge-based authentication
- Magic link authentication

## API Documentation
The complete OpenAPI 3.1.0 specification is available at:
https://api.sherlockdomains.com/openapi-debug.json

All API endpoints are prefixed with `/api/v0/` and include:
- Authentication endpoints (/auth/*)
- Domain management (/domains/*)
- DNS record management (/domains/{domain_id}/dns/*)
- Payment processing (/payments/*)
- User management (/users/*)</doc><doc title="Python SDK"># Sherlock Domains Python SDK

A Python SDK for managing domain names and DNS records through the Sherlock API.

## Installation

```bash
# Install from PyPI
pip install sherlock-domains

# Or install latest from GitHub
pip install git+https://github.com/Fewsats/sherlock-python.git
```

## Core Concepts

- The SDK provides a `Sherlock` class that handles authentication and API interactions
- Uses Ed25519 keypairs for authentication
- Supports domain search, purchase, and DNS management
- Handles contact information required by ICANN
- Supports credit card and Lightning Network payments

## Key Methods

### Authentication & Setup
- `Sherlock(priv='')` - Initialize client with optional private key
- `me()` - Get authenticated user information 

### Domain Management
- `search(q)` - Search for available domains
- `domains()` - List owned domains
- `purchase_domain(sid, domain, payment_method='credit_card')` - Purchase a domain

### Contact Information
- `set_contact_information(first_name, last_name, email, address, city, state, postal_code, country)` - Set ICANN contact info
- `get_contact_information()` - Get current contact information

### DNS Management
- `dns_records(domain_id)` - Get DNS records for a domain
- `create_dns(domain_id, type, name, value, ttl)` - Create DNS record
- `update_dns(domain_id, record_id, type, name, value, ttl)` - Update DNS record
- `delete_dns(domain_id, record_id)` - Delete DNS record

## Common Patterns

1. Domain Search & Purchase:
```python
s = Sherlock()
results = s.search("example.com")
if results['available']:
    purchase = s.purchase_domain(
        results['id'], 
        "example.com",
        payment_method='credit_card'
    )
```

2. DNS Management:
```python
s = Sherlock()
domains = s.domains()
domain_id = domains[0]['id']

# Create DNS record
s.create_dns(
    domain_id,
    type="A",
    name="www",
    value="1.2.3.4",
    ttl=3600
)
```


## Agent Integration

The SDK is designed to be easily integrated with AI agents through the `as_tools()` method, which returns a list of functions ready to be used by LLM tools/functions implementations.

### Available Agent Tools

```python
s = Sherlock()
tools = s.as_tools()
Returns: ['me', '_set_contact_information', '_get_contact_information', '_search', # '_purchase_domain', '_domains', '_dns_records', '_create_dns_record', # '_update_dns_record', '_delete_dns_record']
```

### Integration Example with Claudette

Here's how to enable your AI assistant to handle domain operations using [Claudette](https://claudette.answer.ai), a convenient wrapper for Claude:
```python
from claudette import Chat, models

# Initialize Sherlock
s = Sherlock()

# Create chat with tools
system_prompt = 'You are a helpful assistant that has access to a domain purchase API.'
chat = Chat(models[1], sp=system_prompt, tools=s.as_tools())

# Example interaction
prompt = "Search if domain 'example.com' is available? If it is request a purchase and process the payment using credit card method."
response = chat.toolloop(prompt)
```

The agent can handle complex operations like:
- Domain availability checks
- Purchase requests with payment processing
- Contact information management
- DNS record configuration

Each tool includes detailed documentation in its docstring, allowing the agent to understand:
- Required parameters
- Expected behavior
- Valid input formats
- Common use cases


## Important Notes

1. Contact Information Requirements:
- All fields are required for domain registration
- Must be set before attempting domain purchases
- Validated by ICANN standards

2. Payment Methods:
- credit_card: Returns Stripe checkout URL
- lightning: Returns Lightning Network invoice

3. DNS Record Types:
- Supports standard record types: A, AAAA, CNAME, MX, TXT, etc.
- TTL is specified in seconds (default: 3600)

4. Error Handling:
- Methods raise exceptions for invalid inputs
- 402 status code is expected for payment required
- Contact validation occurs before purchase attempts

## Best Practices

1. Always verify domain availability before purchase
2. Set contact information early in the workflow
3. Store domain_id and record_id values for DNS management
4. Check payment link expiration (typically 30 minutes)
5. Validate DNS record values before creation/updates


## Integration Examples

The SDK includes several example integrations showing different ways to use Sherlock with various LLM platforms:

### FastMCP Integration
```bash
# Quick start with FastMCP
pip install -r requirements.txt
fastmcp dev main.py
```
FastMCP provides a local server that can be used directly in the Claude desktop app. Install it to make the tools available in Claude:
```bash
fastmcp install main.py
```

### OpenAI Integration
Use GPT models to manage domains through natural language:
```python
from cosette import Chat, Client as CosetteClient
from sherlock.core import Sherlock

# Initialize clients
sherlock = Sherlock()
cli = openai.OpenAI(api_key=API_KEY)
cosette_client = CosetteClient(MODEL, cli)

# Create chat with tools
sp = '''You are a helpful assistant that has access to a domain registrar and DNS management API.'''
chat = Chat(cli=cosette_client, sp=sp, tools=sherlock.as_tools())

# Example interaction
response = chat.toolloop("Is example.com available?")
```

### Ollama Integration
For local LLM integration using Ollama:
```python
import openai
from cosette import Chat, Client as CosetteClient
from sherlock.core import Sherlock

# Initialize with local Ollama endpoint
cli = openai.OpenAI(base_url="http://localhost:11434/v1", api_key='not-required')
sherlock = Sherlock()

# Create chat with tools
chat = Chat(cli=cossete_client, sp=system_prompt, tools=sherlock.as_tools())
```

### Streamlit Web Interface
A web interface using Streamlit and Claude:
```python
import streamlit as st
from sherlock.core import Sherlock
from claudette import Chat, models

# Initialize
s = Sherlock()
chat = Chat(models[1], sp=system_prompt, tools=s.as_tools())

# Handle chat in Streamlit
response = chat.toolloop(user_input)

# Sherlock CLI

## Overview

The SDK includes a CLI interface for all operations:

```bash
# Search for domain
sherlock search --q example.com

# Set contact information
sherlock set_contact_information --first_name "Test" --last_name "User" ...

# Create DNS record
sherlock create_dns --domain_id "uuid" --type "A" --name "www" --value "1.2.3.4"
```

## Complete CLI Documentation

```bash
usage: sherlock [-h]
                {me,set_contact_information,get_contact_information,search,purchase_domain,domains,dns_records,create_dns,update_dns,delete_dns,cli_docs}
                ...

positional arguments:
  {me,set_contact_information,get_contact_information,search,purchase_domain,domains,dns_records,create_dns,update_dns,delete_dns,cli_docs}
    me                  Get authenticated user information
    set_contact_information
                        Set the contact information for the Sherlock user
    get_contact_information
                        Get the contact information for the Sherlock user.
    search              Search for domains with a query. Returns prices in USD
                        cents.
    purchase_domain     Request payment information for purchasing a domain.
                        Returns the details needed to complete the payment
                        (like a checkout URL).
    domains             List of domains owned by the authenticated user
    dns_records         Get DNS records for a domain.
    create_dns          Create a new DNS record
    update_dns          Update a DNS record
    delete_dns          Delete a DNS record
    cli_docs            Generate comprehensive CLI documentation in markdown
                        format

options:
  -h, --help            show this help message and exit
```

## Commands

### `me`

```bash
usage: sherlock me [-h]

options:
  -h, --help  show this help message and exit
```

### `set_contact_information`

```bash
usage: sherlock set_contact_information [-h] [--cfn CFN] [--cln CLN]
                                        [--cem CEM] [--cadd CADD] [--cct CCT]
                                        [--cst CST] [--cpc CPC] [--ccn CCN]

options:
  -h, --help   show this help message and exit
  --cfn CFN
  --cln CLN
  --cem CEM
  --cadd CADD
  --cct CCT
  --cst CST
  --cpc CPC
  --ccn CCN
```

### `get_contact_information`

```bash
usage: sherlock get_contact_information [-h]

options:
  -h, --help  show this help message and exit
```

### `search`

```bash
usage: sherlock search [-h] --q Q

options:
  -h, --help  show this help message and exit
  --q Q
```

### `purchase_domain`

```bash
usage: sherlock purchase_domain [-h] --sid SID --domain DOMAIN
                                [--payment_method PAYMENT_METHOD]
                                [--contact CONTACT]

options:
  -h, --help            show this help message and exit
  --sid SID
  --domain DOMAIN
  --payment_method PAYMENT_METHOD
  --contact CONTACT
```

### `domains`

```bash
usage: sherlock domains [-h]

options:
  -h, --help  show this help message and exit
```

### `dns_records`

```bash
usage: sherlock dns_records [-h] --domain_id DOMAIN_ID

options:
  -h, --help            show this help message and exit
  --domain_id DOMAIN_ID
```

### `create_dns`

```bash
usage: sherlock create_dns [-h] --domain_id DOMAIN_ID [--type TYPE]
                           [--name NAME] [--value VALUE] [--ttl TTL]

options:
  -h, --help            show this help message and exit
  --domain_id DOMAIN_ID
  --type TYPE
  --name NAME
  --value VALUE
  --ttl TTL
```

### `update_dns`

```bash
usage: sherlock update_dns [-h] --domain_id DOMAIN_ID --record_id RECORD_ID
                           [--type TYPE] [--name NAME] [--value VALUE]
                           [--ttl TTL]

options:
  -h, --help            show this help message and exit
  --domain_id DOMAIN_ID
  --record_id RECORD_ID
  --type TYPE
  --name NAME
  --value VALUE
  --ttl TTL
```

### `delete_dns`

```bash
usage: sherlock delete_dns [-h] --domain_id DOMAIN_ID --record_id RECORD_ID

options:
  -h, --help            show this help message and exit
  --domain_id DOMAIN_ID
  --record_id RECORD_ID
```

### `cli_docs`

```bash
usage: sherlock cli_docs [-h]

options:
  -h, --help  show this help message and exit
```

</doc><doc title="TypeScript SDK"># Sherlock Domains TypeScript SDK

A TypeScript SDK for managing domain names and DNS records through the Sherlock API.

## Installation

```bash
npm install sherlock-domains
```

## Core Concepts

- The SDK provides a `Sherlock` class that handles authentication and API interactions
- Supports domain search, purchase, and DNS management
- Handles contact information required by ICANN
- Supports credit card and Lightning Network payments

## Key Methods

### Authentication & Setup
- `new Sherlock(accessToken)` - Initialize client with access token
- `me()` - Get authenticated user information 

### Domain Management
- `search(query)` - Search for available domains
- `domains()` - List owned domains
- `purchaseDomain(searchId, domain, paymentMethod='credit_card')` - Purchase a domain

### Contact Information
- `setContactInformation(contact)` - Set ICANN contact info
- `getContactInformation()` - Get current contact information

### DNS Management
- `dnsRecords(domainId)` - Get DNS records for a domain
- `createDns(domainId, {type, name, value, ttl})` - Create DNS record
- `updateDns(domainId, recordId, {type, name, value, ttl})` - Update DNS record
- `deleteDns(domainId, recordId)` - Delete DNS record

## Common Patterns

1. Domain Search & Purchase:
```typescript
const sherlock = new Sherlock('your-token')
const results = await sherlock.search("example.com")
if (results.available) {
    const purchase = await sherlock.purchaseDomain(
        results.id,
        "example.com",
        'credit_card'
    )
}
```

2. DNS Management:
```typescript
const sherlock = new Sherlock('your-token')
const domains = await sherlock.domains()
const domainId = domains[0].id

// Create DNS record
await sherlock.createDns(domainId, {
    type: "A",
    name: "www",
    value: "1.2.3.4",
    ttl: 3600
})
```

## Agent Integration

The SDK is designed to be easily integrated with AI agents through the `asTools()` method, which returns a collection of functions with Zod schemas ready to be used by LLM tools/functions implementations.

### Available Agent Tools

```typescript
const sherlock = new Sherlock()
const tools = sherlock.asTools()
// Returns: me, setContactInformation, getContactInformation, searchDomains,
// purchaseDomain, listDomains, getDnsRecords, createDnsRecord,
// updateDnsRecord, deleteDnsRecord
```

Each tool includes:
- Description
- Zod parameter schema
- Execute function

## Important Notes

1. Contact Information Requirements:
- All fields are required for domain registration
- Must be set before attempting domain purchases
- Validated by ICANN standards

2. Payment Methods:
- credit_card: Returns payment details
- lightning: Returns Lightning Network payment info

3. DNS Record Types:
- Supports standard record types: A, AAAA, CNAME, MX, TXT, etc.
- TTL is specified in seconds (default: 3600)</doc></documentation></project>