@namemyapp/sdk

Official TypeScript SDK for namemy.app — domain availability, one-click BuyURLs, signed webhooks, and agent-attribution helpers.

Runs on Node 20+, Bun, Deno, and Cloudflare Workers. No Node-only imports; HTTP uses platform fetch, signing uses Web Crypto.

Install

pnpm add @namemyapp/sdk
# or
npm install @namemyapp/sdk

Quickstart — check + mint a buy URL

import { NameMyAppClient } from "@namemyapp/sdk";

const nma = new NameMyAppClient({ defaultSource: "my-agent" });
const [first] = await nma.checkDomain(["codeflow"], [".ai", ".dev"]);
if (first?.available) {
  const proposal = await nma.mintBuyUrl({ domain: first.domain });
  console.log(`Send the user here: ${proposal.url}`);
}

That's the whole agent flow: list candidates, hand the user one URL. namemy.app handles checkout, registration, DNS, and email.

Verify outbound webhook deliveries

import { verifyWebhookSignature } from "@namemyapp/sdk/webhooks";

export async function POST(req: Request) {
  const raw = await req.text();
  const ok = await verifyWebhookSignature(
    raw,
    req.headers.get("nma-signature") ?? "",
    process.env.NMA_WEBHOOK_SECRET!,
  );
  if (!ok) return new Response("invalid signature", { status: 400 });

  const event = JSON.parse(raw);
  switch (event.type) {
    case "domain.purchased":
      // event.data.domain, event.data.priceUsd, event.data.source, …
      break;
    case "proposal.minted":
    case "proposal.expired":
      break;
  }
  return new Response("ok");
}

The signature header is Stripe-style: t=<unix>,v1=<hex-hmac-sha256>. Replays older than 5 minutes are rejected automatically.

Agent attribution helpers

import { withAttribution, attributionParams } from "@namemyapp/sdk/agents";

const url = withAttribution("https://namemy.app/buy/x7k2p9aq", "claude-code");
// → https://namemy.app/buy/x7k2p9aq?source=claude-code

const params = attributionParams("my-agent", "session-42");
// → { source: "my-agent", ref: "session-42" }

Use these everywhere you mint a BuyURL by hand — they apply the same character whitelist the API enforces and never overwrite values already present on the input URL.

API reference

| Method | Endpoint | Auth | | --- | --- | --- | | checkDomain(names, tlds) | POST /api/public/domains/check | none | | mintBuyUrl(input) | POST /api/public/domains/check?withProposal=true | none | | getProposal(token) | GET /api/public/proposal/{token} | none | | listSold() | GET /api/public/sold | none |

All public endpoints are IP-rate-limited. For higher quotas and server-to-server purchases, get an API key at https://namemy.app/app/api-keys.

License

MIT