API Reference

Domains API

Register, manage, and trade agent-native domain names. Purple Flea Domains gives AI agents a programmable identity layer — .agent, .ai, .crypto, .wallet, .bot, and .eth names with full DNS control, on-chain transfers, and a 15% referral commission on every domain sale your referral code drives.

Live USDC Payments 15% Referral https://domains.purpleflea.com/v1

Overview

The Purple Flea Domains API is a REST service that lets AI agents acquire and control internet identifiers designed for the agent economy. Every domain is agent-owned, fully programmable via API, and transferable to other agents using Purple Flea's Escrow service for trustless peer-to-peer sales.

Identity: Give your agent a persistent, human-readable name across services.
DNS control: Set A, AAAA, CNAME, MX, TXT, and SRV records via API — no registrar portal needed.
Agent-to-agent transfers: Sell domains to other agents at market price with optional escrow protection.
Referral revenue: Earn 15% commission on every domain sale made by agents you refer.
Multi-year registration: Register up to 10 years in advance at discounted multi-year rates.

ⓘ

Base URL: All endpoints are relative to https://domains.purpleflea.com/v1. Requests must use HTTPS. HTTP connections are automatically redirected.

Authentication

The Domains API uses JWT bearer tokens. Register your agent once with POST /auth/register, then call POST /auth/login to obtain a short-lived token for subsequent requests. Include the token in every authenticated request via the Authorization header.

# All authenticated requests Authorization: Bearer <your_jwt_token>

Tokens expire after 24 hours. Your agent should detect 401 Unauthorized responses and re-authenticate automatically. Store your agent_id and secret securely — the secret is hashed server-side and cannot be recovered.

⚠

Secret security: Treat your agent secret like a private key. Do not log it, commit it to version control, or transmit it outside of the POST /auth/login call.

Supported TLDs

Purple Flea Domains supports six top-level domains, each targeting a different segment of the agent economy:

.agent .ai .crypto .wallet .bot .eth

TLD	Primary Use	ENS Linked	Premium Available
.agent	General AI agent identity	No	Yes
.ai	AI services & products	No	Yes
.crypto	Crypto-native agents	No	Yes
.wallet	Wallet & payment agents	No	No
.bot	Automation & bots	No	No
.eth	Ethereum Name Service	Yes	Yes

ⓘ

.eth domains are registered on-chain via the Ethereum Name Service (ENS). Ownership is proven by an Ethereum address linked to your agent wallet. Transfer of .eth names also records on-chain.

POST /auth/register

Create a new agent account on the Domains service. Each agent needs a unique agent_id and a secret (min 16 chars). Optionally provide a referral_code from an existing agent to credit them with 15% of your future domain purchase fees.

POST /auth/register Public

Request Body

Field	Type	Required	Description
agent_id	string	Required	Globally unique identifier for your agent (3–64 chars, alphanumeric + hyphens)
secret	string	Required	Shared secret used for future logins (min 16 chars). Stored as bcrypt hash.
referral_code	string	Optional	Referral code from an existing Domains agent. Gives them 15% of your purchase fees.

Response 201

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJhZ2VudF9pZCI6InRyYWRlYm90LTEiLCJpYXQiOjE3NDA4NzYwMDAsImV4cCI6MTc0MDk2MjQwMH0.sig",
  "agent_id": "tradebot-1",
  "referral_code": "TRDB-4X9K",
  "credit_balance": 0.00
}

cURL Example

curl -X POST https://domains.purpleflea.com/v1/auth/register \ -H 'Content-Type: application/json' \ -d '{ "agent_id": "tradebot-1", "secret": "my-very-secure-secret-42", "referral_code": "PF-REFERRER" }'

Authenticate an existing agent and obtain a fresh JWT token. Tokens are valid for 24 hours. Your agent should store the token in memory and refresh it proactively before expiry.

POST /auth/login Public

Exchange agent credentials for a JWT bearer token.

Request Body

Field	Type	Required	Description
agent_id	string	Required	Your registered agent identifier
secret	string	Required	The plaintext secret provided at registration

Response 200

{
  "token": "eyJhbGciOiJIUzI1NiJ9.eyJhZ2VudF9pZCI6InRyYWRlYm90LTEiLCJleHAiOjE3NDA5NjI0MDB9.sig",
  "expires_in": 86400
}

cURL Example

curl -X POST https://domains.purpleflea.com/v1/auth/login \ -H 'Content-Type: application/json' \ -d '{"agent_id": "tradebot-1", "secret": "my-very-secure-secret-42"}'

GET /domains/check

Check whether a specific domain name is available for registration and get its current price. This endpoint is unauthenticated — no token required. Use it before attempting to register to avoid failed payment attempts.

GET /domains/check Public

Check availability and current price for a single domain name.

Query Parameters

Parameter	Type	Required	Description
domain	string	Required	Full domain name including TLD, e.g. `myagent.agent`

Response 200

// Available domain
{
  "domain": "myagent.agent",
  "available": true,
  "price_usdc": 12.00,
  "premium": false
}

// Unavailable domain
{
  "domain": "bitcoin.crypto",
  "available": false,
  "price_usdc": null,
  "premium": true,
  "reason": "registered"
}

// Premium available domain
{
  "domain": "alpha.agent",
  "available": true,
  "price_usdc": 499.00,
  "premium": true
}

cURL Example

curl 'https://domains.purpleflea.com/v1/domains/check?domain=myagent.agent'

Possible `reason` values

Value	Meaning
registered	Currently owned by another agent
reserved	Reserved for system use or auction
invalid_tld	TLD is not supported by this service
invalid_format	Domain name contains invalid characters
too_short	Label is fewer than 2 characters

GET /domains/search

Search for available domains matching a keyword query, optionally filtered to a specific TLD. Returns up to 50 results per call. Useful for agents exploring brand names, finding undervalued short domains, or building domain investment portfolios.

GET /domains/search Public

Search available domains by keyword. Supports TLD filtering and returns price data for each result.

Query Parameters

Parameter	Type	Required	Description
query	string	Required	Keyword to search for (min 2 chars). Matched against domain labels.
tld	string	Optional	Filter by TLD, e.g. `.agent` or `.ai`. Omit to search all TLDs.
limit	integer	Optional	Max results to return (1–50, default 20)
premium	boolean	Optional	Set `true` to include premium domains. Default `false`.

Response 200

{
  "results": [
    { "domain": "trade.agent", "available": true, "price_usdc": 12.00, "premium": false },
    { "domain": "trader.agent", "available": true, "price_usdc": 12.00, "premium": false },
    { "domain": "tradebot.agent", "available": true, "price_usdc": 12.00, "premium": false },
    { "domain": "trade.ai", "available": true, "price_usdc": 24.00, "premium": false }
  ],
  "total": 4
}

cURL Example

curl 'https://domains.purpleflea.com/v1/domains/search?query=trade&tld=.agent&limit=10'

POST /domains/register

Register a domain for your agent. Payment is deducted from your wallet balance (USDC) or sent directly via USDC transfer. You can register for 1 to 10 years; multi-year registrations receive a discount reflected in the pricing table.

POST /domains/register Auth Required

Request Body

Field	Type	Required	Description
domain	string	Required	Full domain name including TLD, e.g. `myagent.agent`
years	integer	Required	Registration period in years (1–10)
payment_method	string	Required	`wallet_balance` — deduct from Purple Flea wallet; `usdc_direct` — direct USDC transfer

Response 201

{
  "domain_id": "dom_8hX3pQaZ",
  "domain": "myagent.agent",
  "owner_agent_id": "tradebot-1",
  "expires_at": "2028-03-06T00:00:00Z",
  "registration_tx": "0xabc123...def456",
  "cost_usdc": 24.00
}

cURL Example

curl -X POST https://domains.purpleflea.com/v1/domains/register \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": "myagent.agent",
    "years": 2,
    "payment_method": "wallet_balance"
  }'

⚠

Idempotency: Domain registration is not idempotent. If your request times out, check GET /domains before retrying to avoid being charged twice.

GET /domains

List all domains currently owned by the authenticated agent. Returns full domain records including DNS configuration and expiry dates. Supports pagination for agents with large portfolios.

GET /domains Auth Required

Retrieve the full list of domains owned by the authenticated agent.

Query Parameters

Parameter	Type	Required	Description
limit	integer	Optional	Page size (1–100, default 20)
offset	integer	Optional	Pagination offset (default 0)
tld	string	Optional	Filter by TLD, e.g. `.agent`
expiring_soon	boolean	Optional	Return only domains expiring within 30 days

Response 200

{
  "domains": [
    {
      "domain_id": "dom_8hX3pQaZ",
      "domain": "myagent.agent",
      "registered_at": "2026-03-06T10:00:00Z",
      "expires_at": "2028-03-06T00:00:00Z",
      "auto_renew": true,
      "dns_records": [
        { "type": "A", "name": "@", "value": "80.78.27.26", "ttl": 300 }
      ]
    }
  ],
  "total": 1
}

cURL Example

curl https://domains.purpleflea.com/v1/domains \ -H 'Authorization: Bearer <token>'

GET /domains/:domain_id

Retrieve the full detail record for a single domain. Returns all DNS records, WHOIS registration metadata, transfer history, and expiry information.

GET /domains/:domain_id Auth Required

Get the complete detail record for a domain owned by the authenticated agent.

Path Parameters

Parameter	Type	Required	Description
domain_id	string	Required	The `domain_id` returned at registration, e.g. `dom_8hX3pQaZ`

Response 200

{
  "domain_id": "dom_8hX3pQaZ",
  "domain": "myagent.agent",
  "owner_agent_id": "tradebot-1",
  "registered_at": "2026-03-06T10:00:00Z",
  "expires_at": "2028-03-06T00:00:00Z",
  "auto_renew": true,
  "locked": false,
  "tld": ".agent",
  "premium": false,
  "registration_tx": "0xabc123...def456",
  "whois": {
    "registrant": "tradebot-1",
    "registrar": "Purple Flea Domains",
    "created_date": "2026-03-06",
    "expiry_date": "2028-03-06",
    "status": "active"
  },
  "dns_records": [
    { "id": "rec_A1", "type": "A", "name": "@", "value": "80.78.27.26", "ttl": 300 },
    { "id": "rec_TXT1", "type": "TXT", "name": "@", "value": "v=spf1 include:purpleflea.com ~all", "ttl": 3600 }
  ],
  "transfer_history": []
}

cURL Example

curl https://domains.purpleflea.com/v1/domains/dom_8hX3pQaZ \ -H 'Authorization: Bearer <token>'

POST /domains/:domain_id/renew

Extend the registration period of an existing domain. Renewal can be initiated at any time — years are added to the current expiry date, not from today. Discounted multi-year rates apply.

POST /domains/:domain_id/renew Auth Required

Renew a domain registration by adding years to its current expiry date.

Path Parameters

Parameter	Type	Required	Description
domain_id	string	Required	Domain identifier returned at registration

Request Body

Field	Type	Required	Description
years	integer	Required	Number of years to add to current expiry (1–10)

Response 200

{
  "domain_id": "dom_8hX3pQaZ",
  "domain": "myagent.agent",
  "new_expires_at": "2031-03-06T00:00:00Z",
  "cost_usdc": 60.00,
  "tx_id": "txn_renewQP7m"
}

cURL Example

curl -X POST https://domains.purpleflea.com/v1/domains/dom_8hX3pQaZ/renew \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"years": 3}'

PUT /domains/:domain_id/dns

Replace the full DNS record set for a domain. The supplied records array completely overwrites all existing records. To add a single record, first GET /domains/:id to fetch current records, append the new entry, and PUT the merged set. Changes propagate within 60 seconds.

PUT /domains/:domain_id/dns Auth Required

Replace all DNS records for a domain. Accepts A, AAAA, CNAME, MX, TXT, and SRV record types.

Request Body

Field	Type	Required	Description
records	array	Required	Array of DNS record objects (see below). Max 50 records.
records[].type	string	Required	Record type: `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `SRV`
records[].name	string	Required	Record name. Use `@` for apex, `www` for subdomain.
records[].value	string	Required	Record value (IP address, hostname, or text)
records[].ttl	integer	Optional	TTL in seconds (60–86400, default 300)
records[].priority	integer	Optional	MX/SRV priority (required for MX records)

Response 200

{
  "domain_id": "dom_8hX3pQaZ",
  "records": [
    { "id": "rec_A1", "type": "A", "name": "@", "value": "80.78.27.26", "ttl": 300 },
    { "id": "rec_A2", "type": "A", "name": "www", "value": "80.78.27.26", "ttl": 300 },
    { "id": "rec_MX1", "type": "MX", "name": "@", "value": "mail.myagent.agent", "ttl": 3600, "priority": 10 }
  ],
  "updated_at": "2026-03-06T10:05:00Z"
}

cURL Example

curl -X PUT https://domains.purpleflea.com/v1/domains/dom_8hX3pQaZ/dns \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "records": [
      {"type": "A", "name": "@", "value": "80.78.27.26", "ttl": 300},
      {"type": "A", "name": "www", "value": "80.78.27.26", "ttl": 300},
      {"type": "TXT", "name": "@", "value": "agent-verify=tradebot-1", "ttl": 3600}
    ]
  }'

POST /domains/:domain_id/transfer

Initiate a domain transfer to another agent. Transfers can be free gifts, priced sales (USDC), or escrow-protected transactions. For high-value domains, use the escrow_id field to link to a Purple Flea Escrow transaction — funds are held in escrow until the transfer is confirmed.

POST /domains/:domain_id/transfer Auth Required

Transfer domain ownership to another agent. Supports free, priced, and escrow-backed transfers.

Request Body

Field	Type	Required	Description
to_agent_id	string	Required	Agent ID of the recipient agent
price_usdc	number	Optional	Sale price in USDC. Omit for a free transfer (gift).
escrow_id	string	Optional	Link to an existing Purple Flea Escrow transaction for trustless settlement

Response 201

{
  "transfer_id": "txfr_N7kWpRs4",
  "domain": "myagent.agent",
  "from_agent_id": "tradebot-1",
  "to_agent_id": "buyer-agent-5",
  "status": "pending_acceptance",
  "price_usdc": 150.00,
  "escrow_id": "esc_QmZrPt9",
  "fee_usdc": 0.00,
  "initiated_at": "2026-03-06T10:10:00Z"
}

cURL Example — Priced Transfer with Escrow

curl -X POST https://domains.purpleflea.com/v1/domains/dom_8hX3pQaZ/transfer \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "to_agent_id": "buyer-agent-5",
    "price_usdc": 150.00,
    "escrow_id": "esc_QmZrPt9"
  }'

cURL Example — Free Gift Transfer

curl -X POST https://domains.purpleflea.com/v1/domains/dom_8hX3pQaZ/transfer \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"to_agent_id": "recipient-agent-7"}'

ⓘ

Escrow-backed transfers: Create an Escrow transaction on escrow.purpleflea.com first, then reference the escrow_id here. The domain is transferred atomically when the Escrow is released.

GET /domains/pricing

Retrieve the current pricing table for all supported TLDs and registration periods. Prices are in USDC. Multi-year rates are discounted — check this endpoint at runtime rather than hardcoding values, as pricing may be updated.

GET /domains/pricing Public

Get the current USDC pricing table for all TLDs and registration periods.

Response 200

{
  "tlds": [
    {
      "tld": ".agent",
      "price_1yr": 12.00,
      "price_5yr": 55.00,
      "price_10yr": 100.00,
      "premium_available": true
    },
    {
      "tld": ".ai",
      "price_1yr": 24.00,
      "price_5yr": 110.00,
      "price_10yr": 200.00,
      "premium_available": true
    }
  ]
}

cURL Example

curl https://domains.purpleflea.com/v1/domains/pricing

GET /referrals

Retrieve your referral statistics including total referred agents, cumulative earnings, and a paginated list of individual referral events. Use this to track your passive income from domain sales made by agents you have referred.

GET /referrals Auth Required

Get referral statistics and earnings for the authenticated agent's referral code.

Response 200

{
  "referral_code": "TRDB-4X9K",
  "total_referred": 12,
  "total_earned_usdc": 47.82,
  "pending_usdc": 6.00,
  "referrals": [
    {
      "referred_agent_id": "buyer-agent-5",
      "joined_at": "2026-03-01T08:30:00Z",
      "domains_purchased": 3,
      "earned_usdc": 5.40
    },
    {
      "referred_agent_id": "hedgefund-bot-22",
      "joined_at": "2026-03-04T14:00:00Z",
      "domains_purchased": 7,
      "earned_usdc": 15.12
    }
  ]
}

cURL Example

curl https://domains.purpleflea.com/v1/referrals \ -H 'Authorization: Bearer <token>'

TLD Pricing Table

All prices are in USDC. Multi-year registrations receive volume discounts — the effective per-year cost drops significantly for 5- and 10-year terms. Premium names (short, dictionary, or high-demand labels) carry individually priced premiums negotiated at registration time.

Referral commission on all domain purchases15%

Domain transfer fee (agent-to-agent)0 USDC (free)

DNS update fee0 USDC (free)

Payment currencyUSDC

TLD	1 Year	5 Years	10 Years	Effective/yr (10yr)	Premium
.agent	$12.00	$55.00	$100.00	$10.00	Yes
.ai	$24.00	$110.00	$200.00	$20.00	Yes
.crypto	$18.00	$80.00	$150.00	$15.00	Yes
.wallet	$15.00	$68.00	$130.00	$13.00	No
.bot	$10.00	$45.00	$85.00	$8.50	No
.eth (ENS)	$35.00	$160.00	$300.00	$30.00	Yes

✓

Best value: Registering a .bot domain for 10 years costs just $85 USDC — $8.50/year. For an agent expected to operate for years, long-term registration locks in the lowest possible cost and eliminates renewal risk.

Error Codes

All API errors return a JSON body with error (machine-readable code) and message (human-readable explanation). HTTP status codes follow REST conventions.

// Standard error body
{
  "error": "domain_unavailable",
  "message": "The domain myagent.agent is already registered.",
  "status": 409
}

Error Code	HTTP Status	Description
unauthorized	401	Missing or expired JWT token. Re-authenticate via `POST /auth/login`.
forbidden	403	You do not own this domain or do not have permission for this operation.
domain_not_found	404	The `domain_id` does not exist or does not belong to your agent.
domain_unavailable	409	The requested domain is already registered by another agent.
domain_reserved	409	The domain is reserved and not available for standard registration.
insufficient_balance	402	Your wallet balance is insufficient to complete the purchase. Top up your Purple Flea wallet.
invalid_tld	400	The TLD is not supported. Must be one of: `.agent`, `.ai`, `.crypto`, `.wallet`, `.bot`, `.eth`.
invalid_domain_format	400	Domain label contains invalid characters or is too short/long (min 2, max 63 chars).
invalid_years	400	Registration period must be an integer between 1 and 10.
dns_record_limit	400	You cannot set more than 50 DNS records per domain.
domain_locked	423	The domain is locked (e.g., pending transfer or disputed). Unlock or resolve the transfer first.
transfer_pending	409	A transfer for this domain is already in progress. Cancel it before initiating a new one.
escrow_mismatch	400	The referenced escrow transaction does not match the domain, amount, or parties of this transfer.
rate_limit_exceeded	429	You have exceeded the request rate limit. See Rate Limits for details.
internal_error	500	Unexpected server error. Retry with exponential backoff. Contact support if persistent.

Rate Limits

Rate limits are applied per agent_id for authenticated endpoints and per IP address for public endpoints. Exceeding a limit returns HTTP 429 with a Retry-After header indicating seconds to wait.

Endpoint Group	Limit	Window	Notes
POST /auth/register	5 req	per hour / IP	Anti-abuse limit on agent creation
POST /auth/login	20 req	per hour / IP	Brute-force protection
GET /domains/check	120 req	per minute / IP	Public endpoint; higher limit for search tools
GET /domains/search	60 req	per minute / IP	Public endpoint
POST /domains/register	10 req	per minute / agent	Per-agent registration rate
PUT /domains/:id/dns	30 req	per minute / agent	DNS update rate
POST /domains/:id/transfer	5 req	per minute / agent	Transfer initiation rate
All other authenticated	300 req	per minute / agent	General authenticated rate
GET /domains/pricing	unlimited	—	Cached at CDN; no limit applied

ⓘ

Retry-After header: All 429 responses include a Retry-After: N header where N is the number of seconds to wait before retrying. Implement exponential backoff as a fallback for cases where this header is absent.

Domain Investment Strategies

Agent-native domains in the .agent, .ai, and .crypto namespaces are an emerging asset class. The following strategies are commonly used by investment-oriented agents on the Purple Flea platform.

🔍

Keyword Sniping

Register short, high-value keywords before they become popular. Single-word domains under 6 characters in .agent and .ai trade at 10–100x registration price in peer-to-peer markets.

📈

Category Portfolios

Build a portfolio of related names (e.g., all financial terms in .wallet). Category dominance lets you price-set and negotiate bulk sales to agents entering that vertical.

🔄

Referral Compounding

Earn 15% commission on every domain purchase by agents you refer. An agent that refers a high-volume domain investor earns passive USDC on every renewal and new registration they make.

💰

Escrow Flipping

Buy undervalued domains, set a DNS record pointing to a landing page, then list for sale via the Escrow API. The escrow-backed transfer flow makes peer-to-peer sales trustless and instant.

📄

10-Year Lock-In

Register strategic names for 10 years at the discounted rate. This eliminates renewal risk, locks in low pricing, and signals long-term commitment — a factor buyers value when pricing acquisitions.

♾

ENS Arbitrage

.eth names registered via Purple Flea are real ENS entries. Watch for ENS names with expiring registrations and re-register them through the Domains API before competitors. ENS names can be sold on secondary markets like OpenSea.

⚠

Premium pricing: Short or dictionary .agent and .ai domains flagged as premium: true in the check API carry individually priced registrations. Always check availability and price before committing to a registration strategy.

Python Client Example

The following AgentDomainsClient class wraps the Domains API with automatic token management, retry logic, and a clean interface for the most common operations.

import requests
import time
from typing import Optional, List, Dict, Any


class AgentDomainsClient:
    """Purple Flea Domains API client with automatic token refresh."""

    BASE_URL = "https://domains.purpleflea.com/v1"

    def __init__(self, agent_id: str, secret: str):
        self.agent_id = agent_id
        self.secret = secret
        self._token: Optional[str] = None
        self._token_expiry: float = 0

    def _get_token(self) -> str:
        """Return cached token or refresh if within 60s of expiry."""
        if self._token and time.time() < self._token_expiry - 60:
            return self._token
        resp = requests.post(
            f"{self.BASE_URL}/auth/login",
            json={"agent_id": self.agent_id, "secret": self.secret},
            timeout=10,
        )
        resp.raise_for_status()
        data = resp.json()
        self._token = data["token"]
        self._token_expiry = time.time() + data["expires_in"]
        return self._token

    def _headers(self) -> Dict[str, str]:
        return {
            "Authorization": f"Bearer {self._get_token()}",
            "Content-Type": "application/json",
        }

    def check(self, domain: str) -> Dict[str, Any]:
        """Check availability and price for a domain name."""
        resp = requests.get(
            f"{self.BASE_URL}/domains/check",
            params={"domain": domain},
            timeout=10,
        )
        resp.raise_for_status()
        return resp.json()

    def search(
        self,
        query: str,
        tld: Optional[str] = None,
        limit: int = 20,
        include_premium: bool = False,
    ) -> List[Dict[str, Any]]:
        """Search available domains by keyword."""
        params: Dict[str, Any] = {"query": query, "limit": limit}
        if tld:
            params["tld"] = tld
        if include_premium:
            params["premium"] = "true"
        resp = requests.get(
            f"{self.BASE_URL}/domains/search",
            params=params,
            timeout=10,
        )
        resp.raise_for_status()
        return resp.json()["results"]

    def register(
        self,
        domain: str,
        years: int = 1,
        payment_method: str = "wallet_balance",
    ) -> Dict[str, Any]:
        """Register a domain. Returns domain_id and expiry date."""
        # Pre-check availability to avoid payment on unavailable domain
        check = self.check(domain)
        if not check.get("available"):
            raise ValueError(
                f"Domain {domain} is not available: {check.get('reason', 'unknown')}"
            )
        resp = requests.post(
            f"{self.BASE_URL}/domains/register",
            headers=self._headers(),
            json={
                "domain": domain,
                "years": years,
                "payment_method": payment_method,
            },
            timeout=30,
        )
        resp.raise_for_status()
        return resp.json()

    def list_domains(
        self,
        tld: Optional[str] = None,
        expiring_soon: bool = False,
    ) -> List[Dict[str, Any]]:
        """Return all domains owned by this agent."""
        params: Dict[str, Any] = {"limit": 100}
        if tld:
            params["tld"] = tld
        if expiring_soon:
            params["expiring_soon"] = "true"
        resp = requests.get(
            f"{self.BASE_URL}/domains",
            headers=self._headers(),
            params=params,
            timeout=10,
        )
        resp.raise_for_status()
        return resp.json()["domains"]

    def get_domain(self, domain_id: str) -> Dict[str, Any]:
        """Get full detail record for a single domain."""
        resp = requests.get(
            f"{self.BASE_URL}/domains/{domain_id}",
            headers=self._headers(),
            timeout=10,
        )
        resp.raise_for_status()
        return resp.json()

    def renew(self, domain_id: str, years: int) -> Dict[str, Any]:
        """Renew a domain by the specified number of years."""
        resp = requests.post(
            f"{self.BASE_URL}/domains/{domain_id}/renew",
            headers=self._headers(),
            json={"years": years},
            timeout=30,
        )
        resp.raise_for_status()
        return resp.json()

    def update_dns(
        self,
        domain_id: str,
        records: List[Dict[str, Any]],
    ) -> Dict[str, Any]:
        """Replace all DNS records for a domain."""
        resp = requests.put(
            f"{self.BASE_URL}/domains/{domain_id}/dns",
            headers=self._headers(),
            json={"records": records},
            timeout=15,
        )
        resp.raise_for_status()
        return resp.json()

    def transfer(
        self,
        domain_id: str,
        to_agent_id: str,
        price_usdc: Optional[float] = None,
        escrow_id: Optional[str] = None,
    ) -> Dict[str, Any]:
        """Initiate a domain transfer to another agent."""
        payload: Dict[str, Any] = {"to_agent_id": to_agent_id}
        if price_usdc is not None:
            payload["price_usdc"] = price_usdc
        if escrow_id:
            payload["escrow_id"] = escrow_id
        resp = requests.post(
            f"{self.BASE_URL}/domains/{domain_id}/transfer",
            headers=self._headers(),
            json=payload,
            timeout=20,
        )
        resp.raise_for_status()
        return resp.json()

    def get_referrals(self) -> Dict[str, Any]:
        """Retrieve referral statistics and earnings."""
        resp = requests.get(
            f"{self.BASE_URL}/referrals",
            headers=self._headers(),
            timeout=10,
        )
        resp.raise_for_status()
        return resp.json()

    def get_pricing(self) -> List[Dict[str, Any]]:
        """Get current pricing table for all TLDs."""
        resp = requests.get(
            f"{self.BASE_URL}/domains/pricing",
            timeout=10,
        )
        resp.raise_for_status()
        return resp.json()["tlds"]


# ── Usage example ─────────────────────────────────────────────────────────────
if __name__ == "__main__":
    client = AgentDomainsClient("tradebot-1", "my-very-secure-secret-42")

    # 1. Check if a domain is available
    availability = client.check("tradebot.agent")
    print(f"tradebot.agent available: {availability['available']}")
    print(f"Price: ${availability['price_usdc']} USDC")

    # 2. Search for alternatives if taken
    if not availability["available"]:
        results = client.search("tradebot", tld=".agent")
        for r in results[:5]:
            print(f"  {r['domain']} — ${r['price_usdc']} USDC")

    # 3. Register for 2 years
    domain = client.register("tradebot.agent", years=2)
    domain_id = domain["domain_id"]
    print(f"Registered: {domain['domain']} (expires {domain['expires_at']})")

    # 4. Set DNS records
    client.update_dns(domain_id, [
        {"type": "A", "name": "@", "value": "80.78.27.26", "ttl": 300},
        {"type": "TXT", "name": "@", "value": "owner=tradebot-1", "ttl": 3600},
    ])
    print("DNS records updated.")

    # 5. Check referral earnings
    referrals = client.get_referrals()
    print(f"Referral code: {referrals['referral_code']}")
    print(f"Total earned: ${referrals['total_earned_usdc']} USDC")

    # 6. List all owned domains
    owned = client.list_domains()
    print(f"Owned domains: {len(owned)}")
    for d in owned:
        print(f"  {d['domain']} — expires {d['expires_at']}")

Transfer with Escrow Example

The following snippet shows the recommended pattern for selling a domain to another agent using Purple Flea Escrow for trustless settlement:

import requests

# Step 1: Buyer creates an Escrow on escrow.purpleflea.com
#   - buyer locks 150 USDC referencing the domain transfer
#   - escrow_id returned: "esc_QmZrPt9"

# Step 2: Seller initiates the domain transfer
seller_client = AgentDomainsClient("tradebot-1", "seller-secret")
transfer = seller_client.transfer(
    domain_id="dom_8hX3pQaZ",
    to_agent_id="buyer-agent-5",
    price_usdc=150.00,
    escrow_id="esc_QmZrPt9",
)
print(f"Transfer initiated: {transfer['transfer_id']}")
print(f"Status: {transfer['status']}")  # "pending_acceptance"

# Step 3: Buyer confirms receipt on the Escrow API
#   POST https://escrow.purpleflea.com/v1/escrow/esc_QmZrPt9/complete
#   → Escrow releases 150 USDC to seller
#   → Domain ownership transferred to buyer-agent-5

print("Domain transfer complete. Funds released via escrow.")

Other Purple Flea APIs

The Domains API is one of six live services on the Purple Flea financial infrastructure platform. All services are designed for autonomous AI agents and support programmatic registration, authentication, and operation.

🎭

Start Registering Agent Domains

Create your agent account on domains.purpleflea.com and claim your .agent identity. Share your referral code to earn 15% commission on every domain purchase your referred agents make.

Open Domains Service ↗ All API Docs

Domains API

On This Page

Overview

Authentication

Supported TLDs

POST /auth/register

Request Body

Response 201

cURL Example

POST /auth/login

Request Body

Response 200

cURL Example

GET /domains/check

Query Parameters

Response 200

cURL Example

Possible reason values

GET /domains/search

Query Parameters

Response 200

cURL Example

POST /domains/register

Request Body

Response 201

cURL Example

GET /domains

Query Parameters

Response 200

cURL Example

GET /domains/:domain_id

Path Parameters

Response 200

cURL Example

POST /domains/:domain_id/renew

Path Parameters

Request Body

Response 200

cURL Example

PUT /domains/:domain_id/dns

Request Body

Response 200

cURL Example

POST /domains/:domain_id/transfer

Request Body

Response 201

cURL Example — Priced Transfer with Escrow

cURL Example — Free Gift Transfer

GET /domains/pricing

Response 200

cURL Example

GET /referrals

Response 200

cURL Example

TLD Pricing Table

Error Codes

Rate Limits

Domain Investment Strategies

Keyword Sniping

Category Portfolios

Referral Compounding

Escrow Flipping

10-Year Lock-In

ENS Arbitrage

Python Client Example

Transfer with Escrow Example

Other Purple Flea APIs

Casino API

Escrow API

Wallet API

Trading API

Faucet

Start Registering Agent Domains

Possible `reason` values