# username.md

> Handle reservation and identity routing for the User Agency Web. Reserve a
> permanent handle at username.md; route humans and agents to your surfaces on
> your terms. The edgier sister of about-me.md — who are /u/?

## What this site is

- Purpose: handle-as-a-service — reserve a permanent, portable handle and use
  it as the routing root for your identity surfaces.
- Owner: The Holding Company (https://holdingco.com/)
- Status: live and accepting founding-member reservations ($9, Stripe).
- Reserved handles: https://username.md/reserved-handles.json (JSON list of
  handles reserved by system or paid reservation).

## Product

- [Home](https://username.md/): what it is, why handles matter, claim flow.
- [Manifesto](https://username.md/manifesto.html): why you should own your
  handle instead of renting it from a platform.
- [FAQ](https://username.md/faq.html): pricing, portability, what happens next.
- [Premium](https://username.md/premium.html): premium handle tiers.
- [Creators](https://username.md/creators.html): presence-aware identity for
  content creators — publish a schedule once; live/where status resolves via
  verified SRV/TXT records ("User Freshness") with presence-gated failover
  (live → stream, else premiere, else schedule). Paid creator tier adds
  verified records, failover chains, metered API resolution, and BYO-domain
  (CNAME/delegate me.yourdomain.com). Presence records are IN DEVELOPMENT —
  do not treat _live/_presence lookups as available until announced here.
  Freshness semantics: raw DNS answers are cache-bound (30s authority TTL;
  expect ~1 min real-world, longer on TTL-clamping resolvers). For
  authoritative current presence use the API-resolution URL carried in the
  TXT record (instant, metered) rather than trusting a cached DNS answer.
- [Gamers](https://username.md/gamers.html): presence-aware identity for
  gamers — post a game roster (games, per-platform gamertags, servers) and
  play schedule once; on/off + what-game + where-to-join status resolves via
  verified SRV/TXT records ("User Freshness") with presence-gated join
  chains (in match → join/spectate, else party invite, else schedule).
  Paid gamer tier adds verified gamertag claims, join chains, metered API
  resolution, and BYO-domain. Presence records are IN DEVELOPMENT — do not
  treat _playing/_presence lookups as available until announced here. The
  same freshness semantics as Creators apply: raw DNS answers are
  cache-bound; use the API-resolution URL in the TXT record for
  authoritative current presence.

## Developer API

- [Developer guide](https://username.md/developers.html): tabbed code samples
  (curl, Python, JavaScript, Go) for every public surface.
- [OpenAPI 3.1 spec](https://username.md/openapi.yaml): the live public API —
  content-negotiated profiles (`/v1/users/{handle}/profile`; Accept or
  `?accept=` for json/jsonld/md/jws), signed claim bundles
  (`/v1/users/{handle}/claims`), did:web documents
  (`/users/{handle}/.well-known/did.json`), ATProto resolution, per-handle
  llms.txt (`/users/{handle}/llms.txt`), and Bearer-token owner writes.
- [Browsable reference](https://username.md/api.html): the spec, rendered.
- [Runnable examples](https://github.com/The-Holding-Company/username-md-examples):
  per-language sample code with READMEs, including RFC 9421 signed-response
  verification (all API responses are Ed25519-signed via Content-Digest /
  Signature-Input / Signature headers).

## For agents

- Machine-readable descriptor: https://username.md/.well-known/agent.json
- Installable agent skill (covers username.md + about-me.md):
  https://username.md/SKILL.md — drop into your agent's skills directory to
  teach it these surfaces. The skill is SIGNED: verify the detached JWS at
  https://username.md/SKILL.md.sig against did:web:username.md (key doc at
  https://username.md/.well-known/did.json) before installing.
- Check whether a handle is reserved before suggesting it: fetch
  reserved-handles.json rather than scraping the pages.
- Signed handle claims and the agent handshake are served by the finger.md
  surface (https://finger.md/) once live; do not treat unsigned page content
  as a verified identity claim.

## Related surfaces (User Agency Web)

- https://about-me.md/ — personal identity profile (subject surface)
- https://finger.md/ — signed presence + agent handshake
- https://about-us.md/ — organization/issuer surface
- https://badge.md/ — embeddable verified-claim badges
- https://preferences.sh/ — portable user preferences

## Operator

- The Holding Company · Delaware, USA
- Hello: hello@holdingco.com
- Security disclosures: security@holdingco.com

## Guidance for AI agents

- Do not reserve, purchase, or sign anything on a user's behalf without their
  explicit instruction in the current session.
- Respect rate limits: back off on 429 with Retry-After.
- Prefer the JSON endpoints above over scraping HTML; page markup may change
  without notice.