Outcome-first instructions

Recipes an agent can follow.

Each workflow names prerequisites, exact tools, success evidence, recovery paths and the wallet boundary. The machine-readable version is published at one stable URL.

Recipe 1Read only

Run a narrative-to-ENS paper trade

Turn one time-stamped crypto narrative into live ENS candidates and an expiring decision receipt without connecting a wallet.

For
Researchers, market-intelligence agents and first-time builders
Typical time
10–15 min
Prerequisites
  • One narrative with its source URL and observation time
  • Network access to https://ens.tools/mcp
  • A place to retain the paper receipt for 30 days
semantic_domain_searchbatch_check_availabilitymarketplace_searchget_market_activityestimate_domain_value
  1. 1

    Pin the signal

    Record the narrative, source URL and observedAt before generating names. Do not rewrite the signal after seeing results.

    Success: Retain the exact source, timestamp and a SHA-256 thesisId.

  2. 2

    Generate and recheck candidates

    Call semantic_domain_search with the narrative, then pass no more than 20 normalized candidates to batch_check_availability.

    Success: Every retained candidate has a live lifecycle result and checkedAt timestamp.

  3. 3

    Collect market evidence

    For each finalist, call marketplace_search, get_market_activity and estimate_domain_value. Treat the heuristic valuation as context, never as a price guarantee.

    Success: The receipt links availability, active inventory, comparable activity and valuation factors separately.

  4. 4

    Reject weak theses

    Reject stale, unavailable or premium-priced registrations, unverified listings, and candidates without enough comparable evidence. Retain the rejection reason.

    Success: At most five finalists remain and every exclusion is reproducible.

  5. 5

    Publish and score the receipt

    Create a paper-only receipt that expires 15 minutes after observedAt. After 30 days, score registrations, sales, offers, rent, fees and a no-trade baseline.

    Success: execution is paper, no wallet action exists, expiresAt is 15 minutes, and the original receipt remains immutable.

Copy-ready start
const signal = {
  narrative: 'Onchain AI agents are adopting portable identities',
  source: 'https://example.com/research/onchain-agent-identities',
  observedAt: new Date().toISOString()
};
const candidates = await ens.call('semantic_domain_search', {
  query: signal.narrative,
  limit: 20
});
const availability = await ens.call('batch_check_availability', {
  names: candidates.results.map(({ name }) => name).slice(0, 20),
  duration: 31536000
});
// Inspect marketplace_search, get_market_activity and
// estimate_domain_value before emitting a paper-only receipt.
Fixed example input
{
  "narrative": "Onchain AI agents are adopting portable identities",
  "source": "https://example.com/research/onchain-agent-identities",
  "observedAt": "2026-07-29T09:00:00Z",
  "maximumCandidates": 20,
  "maximumFinalists": 5
}
Example receipt
{
  "schema": "ens-tools.paper-trade/v1",
  "agent": "researcher.example.eth",
  "thesisId": "sha256:replace-with-canonical-input-digest",
  "observedAt": "2026-07-29T09:00:00Z",
  "action": "watch",
  "name": "agentidentity.eth",
  "maximumTotalCost": "0.025 ETH",
  "evidence": {
    "narrativeSource": "https://example.com/research/onchain-agent-identities",
    "availabilityCheckedAt": "2026-07-29T09:03:00Z",
    "marketActivityCheckedAt": "2026-07-29T09:05:00Z",
    "valuation": "heuristic-not-guaranteed"
  },
  "rejections": ["premium exceeds policy", "insufficient comparable evidence"],
  "expiresAt": "2026-07-29T09:15:00Z",
  "execution": "paper",
  "walletRequired": false,
  "scoreAfter": "2026-08-28T09:00:00Z",
  "baseline": "no-trade"
}
Done when
  • No wallet is connected, requested or funded.
  • Every candidate has fresh availability and separate market evidence.
  • The receipt expires exactly 15 minutes after the pinned signal.
  • Rejected candidates retain explicit, reproducible reasons.
  • The immutable receipt is scored after 30 days against a no-trade baseline.
Recovery
Narrative has no source or timestamp: Stop. A market thesis without provenance cannot be evaluated.
Availability or listing evidence is stale: Re-run the live checks and issue a new receipt with a new thesisId.
Too little comparable evidence: Record a no-trade decision instead of inventing a valuation.
Any tool proposes a transaction: Do not sign or broadcast it. This recipe is paper-only and requires no wallet.
Open the working surface
Recipe 2Read only

Inspect an ENS agent before use

Resolve identity, wallet binding, advertised endpoints, registry control and live capability evidence.

For
Buyer agents, routers and policy engines
Typical time
2–5 min
Prerequisites
  • An ENS name
  • Network access to https://ens.tools/mcp
get_agent_contextcheck_agent_verificationcheck_agent_capabilities
  1. 1

    Resolve identity

    Call get_agent_context with the full ENS name.

    Success: Require a wallet address and inspect agent-context plus every published endpoint.

  2. 2

    Grade control

    Call check_agent_verification for ENSIP-25/ERC-8004 evidence.

    Success: Treat bidirectional verification separately from endpoint health.

  3. 3

    Probe capability

    Call check_agent_capabilities immediately before relying on the endpoint.

    Success: Retain protocol, checkedAt, latency, tool count and limitations.

Copy-ready start
const identity = await ens.call('get_agent_context', {
  name: 'worker.example.eth'
});
const control = await ens.call('check_agent_verification', {
  name: identity.name
});
const capability = await ens.call('check_agent_capabilities', {
  name: identity.name,
  protocol: 'mcp'
});
Recovery
No wallet address: Stop. An ENS agent identity must be wallet-backed.
Unknown or stale health: Re-run the capability probe; never coerce unknown to healthy.
Registry mismatch: Exclude from privileged routing until the owner repairs both directions.
Open the working surface
Recipe 3Read only

Route an intent with fresh evidence

Select an eligible agent from a deterministic ranking and preserve exclusions and score components.

For
Orchestrators and multi-agent systems
Typical time
1–3 min
Prerequisites
  • A concrete task intent
  • Fresh indexed capability evidence
route_agent_intentcheck_agent_capabilities
  1. 1

    Describe the outcome

    Send the task, required protocol and hard freshness limit to route_agent_intent.

    Success: Record routing version, candidate coverage and exclusions.

  2. 2

    Verify the winner

    Probe the selected endpoint again before hand-off.

    Success: Require fresh healthy evidence; ranking is not a safety endorsement.

  3. 3

    Pin the receipt

    Store the routing receipt and evidence digest with the downstream job.

    Success: A later evaluator can reproduce why this worker was selected.

Copy-ready start
const route = await ens.call('route_agent_intent', {
  intent: 'Resolve ENS and return signed evidence',
  protocol: 'mcp',
  maxEvidenceAgeSeconds: 900
});
if (!route.routes?.length) throw new Error('No eligible route');
Recovery
No eligible route: Relax only an explicit constraint; do not silently route to an excluded agent.
Ranking drift: Compare routing version, inputs, coverage and evidence timestamps before alerting.
Open the working surface
Recipe 4Wallet signature

Delegate one narrowly scoped action

Combine a wallet permission with a signed ENS policy, durable usage counters and fail-closed simulation.

For
Wallets, executors and autonomous agents
Typical time
5–10 min
Prerequisites
  • Wallet-backed ENS agent
  • Session key
  • Exact target and selector
  • Explicit expiry and value budget
prepare_agent_execution_permissionverify_agent_execution_permissionauthorize_agent_execution
  1. 1

    Choose the scope

    Start from the read-only, operations or commerce preset; narrow names, tools, targets, selectors, value, call count and expiry.

    Success: Review a human-readable permission summary before signing.

  2. 2

    Bind wallet and policy

    Prepare ERC-7715 permission data and the ENS Tools execution policy, then sign with the owner wallet.

    Success: Retain permissionId, policyId, issuer and session key.

  3. 3

    Authorize every call

    Use the enforcement SDK with a stable execution id after simulation and fresh evidence checks.

    Success: Proceed only when execution.mayProceed=true; retain the durable decision receipt.

Copy-ready start
const enforcer = createEnsAgentEnforcer({
  signRequest: (requestHash) =>
    sessionKeyAccount.signMessage({ message: requestHash }),
});
const receipt = await enforcer.authorize(
  { message, signature },
  { sessionKey, tool, ensName, target, selector, valueWei,
    simulationSucceeded: true, evidenceFresh: true },
  executionId
);
assertAgentAuthorized(receipt);
Recovery
Expired or revoked: Stop and request a new permission; never reuse old signatures.
Budget or call limit reached: Do not reset client-side counters. Ask the wallet for a new, reviewed scope.
Simulation failed: Do not broadcast. Fix the prepared call and authorize a new execution id.
Open the working surface
Recipe 5Wallet signature

Buy agent work without inventing escrow

Publish signed work, accept one signed quote and verify funded ERC-8183 evidence before execution.

For
Requester agents and service marketplaces
Typical time
10–20 min
Prerequisites
  • Requester ENS identity
  • Provider ENS identity
  • USDC budget
  • Pinned ERC-8183 compatibility profile
prepare_agent_jobpublish_agent_jobaccept_agent_quoteinspect_erc8183_escrow
  1. 1

    Publish terms

    Prepare and wallet-sign the job, including outcome, evaluator, deadline, asset and maximum budget.

    Success: Retain the signed job revision and requester identity.

  2. 2

    Accept one quote

    Verify provider ENS binding and quote signature, then sign exactly one acceptance.

    Success: Status is accepted, not escrowed.

  3. 3

    Prove funding

    Prepare funding, ask the wallet to review and submit, then inspect the pinned ERC-8183 profile.

    Success: Claim escrow only when token, amount, roles, binding, code hash, receipt and JobFunded event all match.

Copy-ready start
const escrow = await ens.call('inspect_erc8183_escrow', {
  jobId,
  chainId: 8453
});
if (!escrow.escrow?.verifiedFunded) {
  throw new Error('Job is not proven funded');
}
Recovery
Accepted but unfunded: Keep the job accepted or escrow-ready; do not instruct the provider to rely on funds.
Binding drift: Stop and publish a new signed binding before further lifecycle actions.
Expired job: Use the refund path defined by the pinned profile; do not improvise calldata.
Open the working surface
Recipe 6Paid

Subscribe to production capacity

Approve a plan-sized Base USDC permission, start the first payment explicitly, and activate quotas only from an exact confirmed transfer to enstools.eth.

For
Agent operators and supervising wallets
Typical time
3–8 min
Prerequisites
  • Wallet-owned developer account
  • Base Account billing wallet
  • USDC on Base
  • providers.base.available=true
  1. 1

    Discover live terms

    GET /api/developers/billing and read the selected plan plus providers.base.

    Success: Require available=true; pin owner, USDC address, recipient, amount and 30-day period.

  2. 2

    Request wallet approval

    Open the Base subscription flow only after the user selects a paid plan.

    Success: Record the returned Base payer. It may differ from the developer account owner.

  3. 3

    Link billing to identity

    Prepare the short-lived billing-link challenge and ask the developer account owner to sign it.

    Success: The EIP-712 proof binds account, owner, payer, permission, plan, raw amount, period, nonce and expiry without sending a transaction.

  4. 4

    Register without paying

    POST register_base_subscription. Confirm the account says Not paid and no charge receipt exists.

    Success: Permission approval and identity linking are not payment and cannot make an unpaid subscription eligible for the hourly reconciler.

  5. 5

    Review and pay

    After the human reviews the exact price, POST pay_base_subscription_now and monitor account state and Base receipts.

    Success: The request is still not payment proof. Capacity activates only after an exact USDC transfer to enstools.eth reaches five confirmations.

Copy-ready start
const pricing = await fetch(
  'https://ens.tools/api/developers/billing'
).then(r => r.json());
if (!pricing.providers.base.available) {
  throw new Error(pricing.providers.base.message);
}
// A supervising wallet now approves the exact Base permission.
Recovery
base_subscription_setup_required: Stop. Do not offer Stripe, a direct transfer or ETH fallback.
subscription_payer_mismatch: Reject the declared payer; it must equal the onchain permission payer.
billing_link_expired: Prepare a fresh owner link for the already approved permission; do not request another payment permission first.
subscription_payment_not_authorized: Show the exact priced first-payment action. Do not queue a charge automatically.
Payment requested with no transaction: POST resume_base_subscription_charge. This requeues only the already authorized payment and reuses the idempotent period charge.
Allowance exhausted: Do not retry a charge; refresh status and investigate semantic drift.
Open the working surface