# ENS.Tools — Full Agent and Developer Reference

This is the extended machine-readable reference for ENS.Tools. The live MCP
`tools/list` response is canonical for tool names and JSON Schemas.

## Product surfaces

### Find

- `/find/expiry` — lifecycle cohorts: grace, temporary premium, released
- `/search` — natural-language and exact candidate generation with live status
- `/find/discover` — collections and leaderboards
- `/search?mode=bulk` — bulk exact-name checks

### Trade

- `/trade` — active native and aggregated listings
- `/domain/{name.eth}/market` — listing, offers, activity, and wallet fill
- `/trade/sell` — single and bulk Seaport listing flows
- `/trade/insights` — market activity, analytics, and leaderboard
- `/collections` and `/trade/offers` — collection discovery and made/received/collection bids

### Manage

- `/manage` — owner/manager portfolio and renewals
- `/manage/bulk-edit` — record batching
- `/saved?view=watchlist` — tracked names
- `/manage/identity` — reverse resolution and primary-name settings
- `/manage/gas` — renewal gas planning
- `/manage/alerts` — lifecycle alerts and calendar guidance
- `/saved?view=searches` — deterministic monitored queries and match history
- `/inbox` — unified lifecycle, search, marketplace, and transaction action queue

### Identity, portfolio, and network

- `/domain/{name.eth}` — domain, records, authority, security, and protocol detail
- `/resolver/{address}` — resolver inspection
- `/profile` — connected or queried profile lookup
- `/profile/{name-or-address}` — public identity profile
- `/profile/{name-or-address}/portfolio` — public Portfolio 2.0 snapshot, performance, holdings, risk, and activity
- `/network` — registration trends and network analytics; the global market pulse links here
- The header network control explicitly opts into the Sepolia ENSv2 public beta; Ethereum mainnet remains the default

### Agents

- `/agents` — platform overview
- `/agents/my` — connected identity-to-fleet workspace
- `/agents/trust` — evidence and trust-model explanation
- `/agents/my?view=launch` — identity launch plan and wallet executor
- `/agents/discover` — recent ENS names, intent routing, and current capability evidence
- `/agents/discover?mode=capabilities` — live proof-of-capability checks for ENS-published endpoints
- `/agents/my?view=monitoring` — wallet-signed schedules, SLO evidence, and deduplicated incidents
- `/agents/discover?mode=route` — deterministic intent routing across discovered agents
- `/agents/policies` — signed, short-lived, scoped, and revocable sessions for compatible executors
- `/agents/jobs` — signed agent jobs, quotes, acceptances, and verified escrow evidence
- `/agents/my?view=control` — operational fleet view and selected unsigned bulk record plans
- `/agents/trust?view=canary` — signed external control-plane receipts and semantic-drift evidence
- `/agents/my?view=fleets` — subname fleet planner
- `/developers/pricing` — developer capacity plans and payment boundaries
- `/agents/workflows` — goal-oriented agent workflows
- `/agent/{name.eth}` — hosted context, endpoints, and trust grade
- `/developers` — install snippets, live tool catalogue, aggregate usage
- `/developers/console` — wallet-owned API keys, sandbox, usage, and Base USDC subscriptions

Start from a goal when a human request does not name a platform module:

- “Research ENS” → `/agents/workflows#paper-trade-ens-narrative`
- “Name an agent” → `/agents/my?view=launch`
- “Find the right agent” → `/agents/discover?mode=route`
- “Delegate safely” → `/agents/policies`
- “Buy agent work” → `/agents/jobs`
- “Operate a fleet” → `/agents/my?view=control`

Each agent page repeats this goal layer above the lower-level platform-tool
navigation. The same routes are stable for agents and non-JavaScript clients.

### Documentation

- `/docs` — searchable documentation home covering every ENS.Tools product surface
- `/docs/{slug}` — individual user and developer workflow guides
- `/docs/mcp-tools` — complete live tool catalogue generated from the production contract
- `/docs/unsigned-plans` — transaction preparation, simulation, signing, and confirmation
- `/docs/agent-identity-standards` — ENSIP-25/26 and ERC-8004/8217/8183 reference

### Machine-readable editorial content

- `/llms-content.txt` — generated catalogue of every published blog post, guide, and agent recipe
- `/.well-known/content-index.json` — structured index with titles, summaries, dates, stability, and HTML/Markdown URLs
- `/content/blog/index.md` — published blog index
- `/content/blog/{slug}.md` — complete blog post without a JavaScript requirement
- `/content/docs/index.md` — complete documentation index
- `/content/docs/{slug}.md` — complete guide without a JavaScript requirement
- `/content/agents/recipes.md` — all agent recipes, prerequisites, steps, and success conditions

## MCP transport and lifecycle

- Endpoint: `https://ens.tools/mcp`
- Transport: Streamable HTTP, stateless JSON responses
- Current revision: `2025-11-25`
- Supported revisions: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`
- Server version: discover from `https://ens.tools/api/platform`
- Server-initiated SSE listening stream: not supported; an SSE GET returns 405
- Session ids: not issued
- Public authentication: none

Initialize:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": { "name": "example-agent", "version": "1.0.0" }
  }
}
```

Subsequent HTTP requests should send:

```
MCP-Protocol-Version: 2025-11-25
Accept: application/json
Content-Type: application/json
```

The policy API is `https://ens.tools/api/agents/policies`. Supported actions are
`prepare`, `issue`, `prepare_revoke`, `revoke`, and `verify`; a GET with
`policyId` returns the public signed envelope and event trail.

The durable enforcement API is `https://ens.tools/api/agents/enforce`. It
re-resolves ENS, verifies the EOA or ERC-1271 execution-policy signature,
checks the exact request and evidence, and atomically commits call/value usage.
Retries must reuse one stable idempotency key. Proceed only when
`execution.mayProceed` is true. A zero-dependency ESM client and
Express/Connect middleware are published at
`https://ens.tools/sdk/ens-agent-enforcer.mjs`.

The commerce API is `https://ens.tools/api/agents/jobs`. It prepares and
publishes EIP-712 jobs, quotes, and quote acceptances with EOA or ERC-1271
signatures; lists the public job board; prepares draft ERC-8183 `createJob` and
ordered funding plans for a user-selected Base or Ethereum contract; and
inspects and binds escrow evidence. USDC on Base is preferred. WETH is the
ETH-compatible option because the draft requires an ERC-20 payment token.
ERC-8183 is a draft and no canonical deployment is assumed. Exact machine
instructions are at
`https://ens.tools/.well-known/agent-skills/commerce.json`.

The fleet API is `https://ens.tools/api/agents/fleet`. It composes prior public
identity, capability, verification, policy, and commerce evidence for immediate
ENS subnames. A single failed worker dimension is returned as partial evidence
and never fails the rest of the fleet. Fleet inspection includes a deterministic
evidence digest and an explicit attention list. `prepare_fleet_rollout`
re-inspects membership and prepares canary, rolling, or all-at-once phases with
bounded blast radius, semantic gates, manual rollback transactions, and a
portable receipt template. Exact machine instructions are at
`https://ens.tools/.well-known/agent-skills/fleet-operations.json`.

The canary API is `https://ens.tools/api/agents/canary`. It returns immutable
Ed25519-signed receipts from an external read-only runner. The runner identifies
its operator as wallet-backed `enstools.eth`; the receipt-signing key is
separate and has no wallet or transaction authority. Hourly checks compare
the manifest and runtime MCP catalogue, probe positive and negative fixtures,
route fixed intents, verify policy states, enforce escrow truth, and inspect
fleet evidence. Daily checks run browser loading, navigation, and automated
WCAG journeys. Nightly checks exercise malformed payloads, CORS, SSRF
boundaries, and insecure URL rejection. Use
`get_control_plane_canary_status` from MCP. Check receipt freshness,
signature verification, and semantic assertions; an HTTP 200 alone is not a
passing result. Exact verification instructions are at
`https://ens.tools/.well-known/agent-skills/control-plane-canary.json`.

## Tool groups

### ENS reads

- `lookup_domain` — owner, resolver, registration and lifecycle
- `resolve_records` — Universal Resolution address/avatar/contenthash/text
- `check_expiry` — batch lifecycle
- `search_domains` — indexed substring search of registered names
- `semantic_domain_search` — natural-language candidate generation and status
- `batch_check_availability` — up to 50 live registrar checks and wrapper quotes
- `get_owner_domains` — address portfolio
- `get_primary_name` — reverse resolution
- `get_name_price` — current registrar price and displayed platform fee
- `get_subnames_for_name` — indexed child names
- `get_name_history` — registrations, renewals, transfers, resolver changes
- `estimate_domain_value` — heuristic only; not a market guarantee
- `get_gas_estimate` — current gas and operation estimate
- `resolve_chain` — hierarchical resolver/owner debugging; this is not a cross-chain address tool

### Agent identity and trust

- `get_agent_context` — ENSIP-26 `agent-context` and protocol endpoints
- `discover_agents` — capability-aware directory across live ENS records and recent observed tools/skills, with protocol, health, freshness, verification, and sorting controls
- `check_agent_capabilities` — probe ENS-published MCP, A2A, and web endpoints
- `get_agent_capability_history` — retrieve stored point-in-time observations
- `route_agent_intent` — deterministically rank only eligible capability matches and return a versioned receipt, evidence digests, score breakdown, and exclusion reasons
- `prepare_agent_policy` — prepare a scoped, short-lived EIP-712 authorization for a compatible executor
- `publish_agent_policy` — verify the issuer signature and publish the policy plus issuance event
- `get_agent_policy` — read the signed policy and event trail
- `verify_agent_policy` — verify signature and live scope for a requested tool, ENS name, and value
- `prepare_agent_policy_revocation` — prepare an issuer-signed revocation
- `revoke_agent_policy` — verify and publish a revocation
- `check_agent_verification` — ENSIP-25 + registry-side grading
- `check_agent_binding` — ERC-8217 metadata and binding contract
- `get_agent_reputation` — ERC-8004 summary scoped to supplied reviewers/tags
- `prepare_erc8004_registration` — registration file + unsigned mint
- `prepare_erc8004_uri_update` — complete post-mint registration entry
- `provision_agent_identity` — phased launch plan

New ERC-8004 identities require two phases because `agentId` is assigned by the
confirmed mint:

1. mint with a bootstrap registration URI;
2. read `agentId` from `Registered`;
3. update agentURI with a file containing `eip155:1:<registry>` + `agentId`;
4. publish the ENSIP-25 record with the ERC-7930 registry encoding.

### Agent commerce

- `prepare_agent_job` — prepare a requester-signed budget, deadline, capability scope, target, and evaluator
- `publish_agent_job` — verify and publish the signed job
- `prepare_agent_quote` — prepare a provider-signed ENS identity, price, delivery, and terms
- `publish_agent_quote` — verify the provider signature, job constraints, and current ENS resolution
- `prepare_agent_quote_acceptance` — prepare the requester signature selecting exactly one quote
- `accept_agent_quote` — publish the acceptance atomically and close the job to further quotes
- `get_agent_job` and `list_agent_jobs` — read signed objects, visible ENS-binding status, settlement state, and event trail
- `prepare_erc8183_create_job` — inspect user-selected Base or Ethereum bytecode and prepare current draft reference calldata
- `prepare_erc8183_funding` — verify the created job and return ordered provider setBudget, optional ETH-to-WETH wrap, exact ERC-20 approval, and requester funding transactions
- `inspect_erc8183_escrow` — compare contract code hash, job roles, description, expiry, current ENS binding, payment token, exact quote budget, funded state, receipt, client, amount, and `JobFunded` event
- `prepare_erc8183_binding` and `publish_erc8183_binding` — requester-sign and persist the evidence only after every comparison passes
- `prepare_erc8183_submit` — re-read the signed binding and live contract, then prepare provider-only submission with a non-zero deliverable commitment
- `prepare_erc8183_complete` — prepare evaluator-only completion and preview the contract-reported completion fees
- `prepare_erc8183_reject` — prepare rejection from the client or evaluator required by the current state
- `prepare_erc8183_refund` — prepare permissionless refund calldata only after a funded/submitted job reaches onchain expiry
- `inspect_erc8183_outcome` — report live state, parties, economics, and matching submit/complete/reject/refund events

Settlement labels are strict:

- `open` — a signed work order accepts quotes
- `expired-unaccepted` — the quote deadline elapsed without an accepted quote
- `escrow-ready` — one quote has a signed acceptance; no locked funds are claimed
- `escrowed` — matching funded ERC-8183-compatible onchain evidence has been verified

The ERC-8183 evaluator is a trusted role and the draft does not itself provide
arbitration. Its prose and reference implementation currently disagree on
selected parameters, so use the exact signatures and selectors in
`https://ens.tools/.well-known/agent-skills/erc8183-profile.json`. Contract
hooks add further execution risk. Simulate and review the specific deployment
before signing. Use USDC on Base by default. Native ETH must be wrapped to WETH
before ERC-8183 funding.

### Fleet control

- `inspect_agent_fleet` — inspect up to 50 immediate ENS subnames; return identity readiness, stored endpoint health, verification grade, active policy, signed work, routeability, and partial-evidence errors
- `prepare_fleet_updates` — prepare endpoint, context, pause, or resume records for up to 25 exact selected workers
- `prepare_fleet_rollout` — re-inspect exact membership and group independent updates into gated canary or rolling phases with max-unavailable limits, prepared manual rollback, and a portable receipt template

Health semantics are strict: `unknown`, `stale`, `degraded`, `failed`,
`paused`, and `healthy` remain separate. Stored observations older than 24
hours are stale. One worker or evidence-source failure never marks another
worker failed and never upgrades missing evidence to healthy.

Every prepared fleet update is an independent unsigned Public Resolver
transaction. Simulate and review each before signing. `agent-status` is an
ENS.Tools advisory record rather than an ENS standard; third-party software
must explicitly choose to honor it.

Fleet rollout plans never broadcast, self-heal, continue automatically, or
roll back automatically. After each phase, read back the exact records, collect
fresh capability evidence, verify unselected workers did not regress, and stop
on any semantic gate failure.

### Unsigned ENS actions

- `prepare_registration_commit`
- `prepare_registration_reveal`
- `prepare_renewal` (single or bulk)
- `prepare_set_records`
- `prepare_transfer`
- `prepare_set_primary_name`
- `prepare_create_subname`
- `prepare_agent_fleet`

Registration commit secrets must remain private between phases. Reveal inputs
must exactly match the commit, and the commitment should be at least 60 seconds
old. Record values are public; never place credentials or secrets in ENS.

### Marketplace

- `marketplace_search`
- `marketplace_listing`
- `marketplace_stats`
- `get_market_activity`
- `prepare_marketplace_listing`
- `prepare_marketplace_offer`
- `prepare_marketplace_purchase`

Prepared listing and offer results include Seaport EIP-712 typed data and the
backend submission template. Purchase preparation accepts a signed basic order
and returns atomic fill calldata. Re-check current ownership, order expiry,
counter, and approval before signing.

### Safety and status

- `simulate_transaction` — `eth_call` + `eth_estimateGas`; no broadcast
- `get_transaction_status` — not-found, pending, confirmed, or reverted
- `get_agent_platform_capabilities` — current feature flags

An unsigned plan has:

```json
{
  "kind": "ens-tools-unsigned-plan",
  "chainId": 1,
  "safety": {
    "broadcasts": false,
    "privateKeysAccepted": false,
    "walletSignatureRequired": true,
    "simulateBeforeSigning": true
  },
  "prerequisites": [],
  "transactions": [
    {
      "id": "tx-1",
      "to": "0x...",
      "data": "0x...",
      "value": "0",
      "description": "Human-readable action",
      "dependsOn": []
    }
  ]
}
```

## Agent identity records

ENSIP-26:

```
agent-context
agent-endpoint[mcp]
agent-endpoint[a2a]
agent-endpoint[web]
```

ENSIP-25:

```
agent-registration[<ERC-7930 interoperable registry address>][<agentId>] = "1"
```

Ethereum mainnet registry encoding uses:

```
0x00010000010114 + 20-byte registry address
```

Verification grades:

- `bidirectional` — the onchain identity exists, its registration file names
  the ENS identity, and the controlling address agrees
- `registered-custodial` — the file and ENS record agree but identity custody is
  held by another party
- `self-asserted` — the ENS claim cannot be completed from registry evidence
- `mismatch` — the registry file points at a different name
- `none` — no ENSIP-25 record

These grades verify identity linkage, not software quality, endpoint safety, or
truth of capabilities.

## Contract and fee paths

- ENS Registry: `0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e`
- Public Resolver: `0x231b0Ee14048e9dCcD1d247744d114a4EB5E8E63`
- Base Registrar: `0x57f1887a8BF19b14fC0dF6Fd9B2acc9Af147eA85`
- Latest ETH Registrar Controller: `0x59E16fcCd424Cc24e280Be16E11Bcd56fb0CE547`
- Wrapped legacy registrar controller: `0x253553366Da8546fC250F225fe3d25d0C782303b`
- Name Wrapper: `0xD4416b13d2b3a9aBae7AcD5D6C2BbDBE25686401`
- Seaport 1.6: `0x0000000000000068F116a894984e2DB1123eB395`
- Fee recipient: enstools.eth

Native ENS.Tools marketplace orders include an atomic 2% fee. Registration and
renewal preparation calls the deployed ENS.Tools wrappers and returns the live
quote, including the displayed platform fee and value buffer. Agents must not
describe platform fees as ENS protocol fees.

Network activity must aggregate both registrar controllers. New registrations
emit the referral-aware `NameRegistered(...,bytes32 referrer)` event on the
latest controller, while legacy-compatible renewals can still be emitted by the
wrapped controller. A healthy renewal count from one controller is not evidence
that registration coverage is complete.

## Lifecycle

1. Active
2. Expiring (under 90 days)
3. Grace period (90 days; previous owner can renew)
4. Temporary premium (21-day declining premium after grace)
5. Released (111 days after expiry)

## Authentication and machine payments

The anonymous MCP baseline remains deliberate. Production runtimes can create
wallet-owned, revocable API keys at:

`https://ens.tools/developers/console`

Use `https://ens.tools/api/v1/tools` with a Bearer key and stable
`Idempotency-Key`. Every live or deterministic sandbox call returns a durable
quota receipt. API key secrets are shown once; only SHA-256 hashes are stored.
Request arguments are not retained in the quota ledger.

The direct Operator purchase journey is:
`https://ens.tools/developers/console?plan=operator#subscribe`.

Generated API and client references:

- `GET https://ens.tools/api/openapi.json`
- `https://ens.tools/sdk/ens-agent-client.mjs`
- `https://ens.tools/.well-known/agent-skills/developer-platform.json`
- `https://ens.tools/.well-known/agent-pricing.json`

Operator, Team, and Scale plans renew every 30 days through a Base Account
spend permission denominated in official Base USDC on chain 8453. Every charge
is sent to enstools.eth. Entitlement is applied only after five confirmations
prove the exact payer, recipient, token, amount, transaction and period. A
permission approval and the developer-owner link create no payment and queue no
charge. The console remains Not paid until a human separately reviews the price
and explicitly starts the first payment. That request and a transaction hash
alone are still not payment evidence. A Base Account is Coinbase’s
self-custodial smart wallet, not every wallet connected to Base. Existing Base
App or Smart Wallet users can sign in; a new human payer can create one with
email or a passkey without a Coinbase exchange account. It has a separate
official-Base-USDC balance from the developer-owner wallet. If approval
completed but linking was interrupted, `Already approved? Recover it`
authenticates the same Base Account and accepts only its exact active ENS.Tools
permission; it requests no new allowance or payment. Stripe,
one-off transfers, ETH payments and per-call x402 are disabled. Paid capacity
never changes directory rank, verification, health, policy authorization,
canary evidence, or escrow truth. OAuth, ERC-8128, and MPP remain disabled.

This subscription contract is separate from two other money flows. Agent-job
escrow may use allowlisted USDC or WETH on Base or Ethereum through a
user-selected ERC-8183-compatible contract; native ETH must be wrapped to WETH.
ENS registration, renewal, network gas, and marketplace settlement are separate
onchain costs. Neither flow activates authenticated platform capacity.

## Usage and privacy

`https://ens.tools/api/agents/stats` publishes aggregate 30-day call count,
success rate, average duration, tools used, top-tool counts, and protocol-stage
reach from non-browser discovery through initialize, tools/list, tools/call,
and successful calls. It does not publish arguments, caller identities, wallet
addresses, user agents, protocol sessions, or raw rows. Stage counts are not
joined into an identifiable cohort.

## Other public APIs

- `GET /api/marketplace/listings`
- `GET /api/marketplace/listings/{name}`
- `GET /api/marketplace/activity`
- `GET /api/marketplace/stats`
- `GET /api/market/pulse` — rolling registrar, marketplace, sales, and collection snapshot
- `GET /api/portfolio/{name-or-address}` — public Portfolio 2.0 snapshot or explicit build state
- `POST /api/search/semantic`
- `GET /api/network`
- `GET /api/health`
- `GET /api/platform` — generated platform version, stable routes, safety contract, counts, and complete MCP schemas

## Contact

- Site: https://ens.tools
- Email: hello@ens.tools
- X: @enstools