LobsterDomains.xyz — Skills for AI Agents

Base URL: https://lobsterdomains.xyz

You are an AI agent that can register domain names on behalf of users.
Read this file to understand how to check availability, price domains, and complete a full purchase.

Authentication

All API endpoints require a Bearer token in the Authorization header.

Authorization: Bearer <api_key>

API keys are managed at: https://lobsterdomains.xyz/api-keys

To get a key:
1. Go to https://lobsterdomains.xyz/api-keys
2. Sign in with your Ethereum wallet (MetaMask or similar)
3. Click "Generate API Key", give it a label (e.g. "My Claude Agent")
4. Copy the key — it starts with ld_
5. Tell your agent: "My LobsterDomains API key is: ld_xxxx — read https://lobsterdomains.xyz/skills.md for instructions."

Step 1 — Check availability

GET /api/v1/domains/check?domain=<domain>
Authorization: Bearer <api_key>

Response:

{

  "ok": true,

  "domain": "example.com",

  "available": true,

  "price_usd": 13.50,

  "currency": "USDC"

}

If available is false, the domain is already registered. Suggest an alternative.

Wallet access for payments

The API requires an on-chain payment before registration. There are two ways to handle this:

### Option A — Ask the human to pay (recommended, no private key needed)

Tell the user the exact amount and address, wait for them to confirm the transaction, and ask them to paste the transaction hash. This is the safest approach.

Example agent message:
> "Please send 13.50 USDC to 0x8939E62298779F5fE1b2acda675B5e85CfD594ab on Ethereum (or Arbitrum/Base/Optimism). Once confirmed, paste the transaction hash here."

### Option B — Dedicated agent wallet (for fully autonomous agents)

If you need to pay without human interaction, ask the owner to:
1. Create a new, separate wallet dedicated to this agent (never the owner's main wallet)
2. Fund it with only the amount needed — do not transfer more than necessary
3. Share that wallet's private key with you

For signing and sending ERC-20 transactions in code, use a library like [viem](https://viem.sh) or [ethers.js](https://docs.ethers.org).

Step 2 — Send payment on-chain

Transfer the exact price_usd amount (× years) in USDC or USDT to the receiving address.

Receiving address: 0x8939E62298779F5fE1b2acda675B5e85CfD594ab

### Stablecoins (recommended)

Transfer the exact price_usd amount (× years) in USDC or USDT to the receiving address.

Receiving address: 0x8939E62298779F5fE1b2acda675B5e85CfD594ab

### Native ETH (not recommended — use only if necessary)

Set currency: "ETH" and chain to one of: ethereum, arbitrum, base, optimism.
The USD value of the ETH sent must exceed the domain price at the time the API verifies it.
Exclude gas fees from your calculation.
Fetch the current ETH price first:

GET /api/v1/prices
Authorization: Bearer <api_key>

Response: { "ETH": 3200.50, "BTC": 65000.00 }

Send native ETH (not an ERC-20 token) to the same receiving address:
0x8939E62298779F5fE1b2acda675B5e85CfD594ab

### Bitcoin (not recommended — highest complexity)

Set currency: "BTC". The chain field is ignored.
Bitcoin receiving address: configured per server — check with the operator.
The USD value of the BTC sent must exceed the domain price at the time the API verifies it.
Verification uses current BTC price from CoinGecko and the Blockstream API to confirm the transaction.
Set payment_tx to the Bitcoin transaction ID (txid).

Step 3 — Register the domain

POST /api/v1/domains/register
Authorization: Bearer <api_key>
Content-Type: application/json
{

  "domain": "example.com",

  "years": 1,

  "currency": "USDC",           // USDC | USDT | ETH | BTC

  "chain": "ethereum",          // ethereum | arbitrum | base | optimism (ignored for BTC)

  "payment_tx": "0x<transaction_hash>",

  "nameservers": ["ns1.afraid.org", "ns2.afraid.org", "ns3.afraid.org", "ns4.afraid.org"],  // optional, defaults to afraid.org

  "contact": {

    "first_name": "Jane",

    "last_name": "Doe",

    "org_name": "",

    "email": "jane@example.com",

    "phone": "+1.5551234567",

    "address1": "123 Main St",

    "city": "New York",

    "state": "NY",

    "postal_code": "10001",

    "country": "US"

  }

}

Response on success:

{

  "ok": true,

  "order_id": 42,

  "domain": "example.com",

  "status": "completed",

  "opensrs_order_id": "12345678",

  "manage_url": "https://manage.opensrs.net/?token=..."

}

Pass the manage_url back to the user so they can configure DNS, transfers, and renewals.

Step 4 — Query orders & get management credentials

GET /api/v1/orders
Authorization: Bearer <api_key>

Returns all orders for this API key's owner (latest 50).

Filter to a specific domain:

GET /api/v1/orders?domain=example.com

Authorization: Bearer <api_key>

Response for a completed order:

{

  "ok": true,

  "orders": {

    "order_id": 9,

    "domain": "example.com",

    "status": "completed",

    "nameservers": ["ns1.afraid.org", "ns2.afraid.org", "ns3.afraid.org", "ns4.afraid.org"],

    "opensrs_order_id": "381903363",

    "opensrs_username": "jane",

    "opensrs_password": "Abc123xyz...",

    "manage_url": "https://manage.opensrs.net/"

  }

}

The agent can use opensrs_username + opensrs_password to log into manage.opensrs.net on behalf of the user to manage DNS, transfers, and renewals (including extending the registration period).

Renewals (important)

LobsterDomains does not use subscription billing for renewals.

- Domains are registered with let-expire / let-go behavior enabled.
- If renewal is not paid in time, the domain may expire and be released.
- Agents should proactively remind users to renew early from the management portal.
- In UI terms, this is the Extend period action in domain management.

Typical renewal guidance an agent can send:

> "Your domain is not auto-renewed by subscription. Please open your management portal and use Extend period before expiry to avoid losing the domain."

Notes

- years must be between 1 and 10.
- contact.country must be a 2-letter ISO code (US, GB, DE, …).
- contact.phone must start with a + and country code, e.g. +1.5551234567.
- payment_tx is the ERC-20 transfer transaction hash. The server verifies it is included before registering.
- If OpenSRS registration fails after a successful payment, the order is saved as paid and can be retried by the account owner.
- Pricing for all supported TLDs: https://lobsterdomains.xyz/pricing

Full agent workflow (pseudocode)

1. ask user: what domain do they want?
2. GET /api/v1/domains/check?domain={domain}  → check available + price
3. confirm price with user
4. ask user to sign & send {price_usd * years} USDC to 0x8939...594ab on their preferred chain
5. wait for 3 confirmations, capture tx hash
6. POST /api/v1/domains/register with domain + contact + payment_tx
7. return manage_url to user
8. (later) GET /api/v1/orders?domain={domain}  → retrieve credentials to manage DNS / renewals
9. remind user to use Extend period before expiry (no subscription auto-renew)