How it works — USERNAME.md

What a handle is

A handle is a name you own on the web: username.md/you. It's a real web page people can visit, and a real address programs can look up. It lists the accounts you choose to share — GitHub, Bluesky, your website, your email — all in one place, under one name. Change a link once and everyone who looks you up gets the new answer.

# a handle is a page in a browser — and an address in a terminal $ curl -s -H 'accept: application/json' https://username.md/v1/users/chris/profile

What "signed identity" means

Every answer your handle gives is cryptographically signed — sealed with a key that only username.md controls, verifiable against public keys anyone can fetch. When an app, a person, or an AI agent looks you up, they don't have to take the page's word for it: the math proves the answer really came from your handle and wasn't tampered with. A profile page says who you are. A signed profile proves it.

# See the signature headers on any response $ curl -sI -H 'accept: application/json' https://username.md/v1/users/chris/profile \ | grep -iE 'content-digest|signature' # Content-Digest: sha-256=:<base64(sha256(body))>: # Signature-Input: sig1=("content-digest" "@authority");created=...;keyid="platform-ed25519";alg="ed25519" # Signature: sig1=:<base64(ed25519 signature)>:

For developers: RFC 9421 HTTP Message Signatures, did:web, and W3C Verifiable Credentials — verification code in four languages lives in the developer guide.

What AI agents do with your handle

More and more of what visits the web isn't a person — it's software acting for a person. Agents fetch username.md/you as JSON or Markdown, check the signature, and get your links, your keys, and your rules for how you want to be contacted. You publish once, on your terms. (Agents get their own instructions too — your handle serves its own llms.txt.)

# Markdown for terminals and LLMs $ curl -s -H 'accept: text/markdown' https://username.md/v1/users/chris/profile # Instructions for AI agents interacting with this handle $ curl -s https://username.md/users/chris/llms.txt

Verified claims

Anyone can type a GitHub URL into a bio. On username.md, you can prove it. Verify a domain with a DNS record, bind your Bluesky account so @you.username.md resolves across the network, or import your old Keybase proofs — each check becomes a signed claim anyone can verify, even offline. Your profile stops being a list of links and becomes a list of facts.

$ curl -s https://username.md/v1/users/chris/claims # → { "did": "...", "public_jwk": {...}, "claims": [ { "type": "atprotoHandle", "jws": "...", ... } ] }

Portability

Your handle routes to you — not the other way around. Own a domain? Your handle can resolve to did:web:yourname.com. Everything is open formats over plain HTTPS. No walled garden, including ours.

# did:web document (public keys + service endpoints) $ curl -s https://username.md/users/chris/.well-known/did.json

Radical honesty

What's live today vs. what's coming

No fine print, no vapor. This table is the truth as of today.

Capability	Status
Profile API with content negotiation (HTML, JSON, Markdown, JSON-LD, signed JWS)	LIVE
Signed responses on every API answer (RFC 9421, Ed25519, public keys)	LIVE
Verified claims + DNS-TXT domain verification	LIVE
ATProto / Bluesky binding (@you.username.md)	LIVE
Keybase import — proofs and PGP key re-verified and re-signed	LIVE
Email forwarding ([email protected])	LIVE
Developer docs + OpenAPI 3.1 spec	LIVE
Creator / gamer presence records ("User Freshness")	IN DEVELOPMENT
1–3 character handle auction	IN DEVELOPMENT
Handle transfers — ship at launch	IN DEVELOPMENT

Kept in sync with llms.txt, the same status file we serve to AI agents. More questions? See the FAQ.

Own the name that answers for you

Claim your handle — $9 Read the developer guide

Founding access: $9 reserves your handle today. The profile API, signed responses, and Bluesky binding are live now; full refund if we don't ship the rest by 2026-09-30.