Developer accounts, sandbox, quotas, and Base subscriptions

Before you run this workflow

How to use it

1. 1

   Create the wallet-owned account

   Open the developer console, connect the owner wallet, read the ten-minute EIP-712 challenge, and sign. This grants no token or transaction permission.

2. 2

   Store the key once

   Copy the ensk_live_ secret into the runtime secret manager. Do not place it in ENS records, prompts, logs, client-side bundles, or source control.

3. 3

   Exercise semantic fixtures

   Call the sandbox environment first. Test healthy and unhealthy capability evidence, routing order, active/expired/revoked policy states, and accepted-but-unfunded escrow truth.

4. 4

   Move the same client live

   Switch from client.sandbox to client.live. Supply a stable Idempotency-Key for every call and retain the returned quota receipt.

5. 5

   Discover live subscription readiness

   GET /api/developers/billing and require providers.base.available=true. Pin the plan amount, subscription owner, official Base USDC address, enstools.eth recipient and 30-day period.

6. 6

   Create or sign in to the Base Account

   Open /developers/console?plan=operator#subscribe for the 39 USDC Operator journey, or choose another plan. Your MetaMask or other connected wallet remains the developer-account and ENS owner. Billing opens keys.coinbase.com: sign in if you already use Base App or Smart Wallet, or create a self-custodial Base Account with email or a passkey. A Coinbase exchange account is not required.

7. 7

   Fund and approve the billing limit

   The Base Account is a distinct wallet and needs the plan amount in official USDC on Base. Use Fund from another wallet if necessary, then approve the capped recurring permission. Approval sets a revocable limit; it does not move USDC or pay for the plan.

8. 8

   Recover an interrupted approval

   If the approval succeeded but linking failed or the page reloaded, choose Already approved? Recover it. Sign in to the same Base Account so the console can find only that payer’s exact active ENS.Tools permission. Recovery requests no new allowance and makes no payment.

9. 9

   Link the payer to the owner

   After Base approval, sign the exact account, payer, permission, plan, amount, period, nonce and expiry with the developer-account owner. This is not a transaction, does not move ENS ownership and adds no token permission.

10. 10

    Review and start the first payment

    Registration leaves the account Not paid. Review the displayed plan and click Pay … USDC now. This separately recorded action is required before any initial or hourly charge job may run.

11. 11

    Resume a stuck payment request

    If Payment requested does not produce a Base transaction, use Resume payment or POST resume_base_subscription_charge. The worker reuses the already authorised, period-idempotent charge; it does not create a second permission or prove payment.

12. 12

    Confirm, then rely on entitlement

    A requested payment is not a paid payment. Capacity remains inactive until the console exposes a Base transaction and the exact transfer to enstools.eth reaches five confirmations.

Deterministic sandbox fixtures

Errors and recovery

Plan contract

Examples

import { createEnsToolsClient } from 'https://ens.tools/sdk/ens-agent-client.mjs';

const ens = createEnsToolsClient({
  apiKey: process.env.ENS_TOOLS_API_KEY,
});

const fixture = await ens.sandbox(
  'check_agent_capabilities',
  { name: 'unhealthy.agent-fixture.eth' },
  { requestId: 'test:capability:001' },
);

const live = await ens.live(
  'lookup_domain',
  { name: 'vitalik.eth' },
  { requestId: 'production:lookup:001' },
);

curl https://ens.tools/api/v1/tools \
  -H "Authorization: Bearer $ENS_TOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: production:lookup:001" \
  -d '{
    "environment": "live",
    "tool": "lookup_domain",
    "arguments": { "name": "vitalik.eth" }
  }'

Related guides