Handles and messageboxes
These are incubating, gated contracts. Allocation and discovery flags are off by default. A deployed route or account Handle page does not imply public activation or production-proven wallet custody. Inspect the live auth-host manifest before advertising discovery.
Handle lifecycle
Select the profile's Handle page at /account/{bapId}/handle. The supported flow checks availability, reserves a handle, acquires the required certificate through the wallet, and activates the binding only with its required custody/evidence. Reservation alone is not a resolvable identity.
The management family is /api/brc169/handles/availability, /allocations, /activations, /current, /discoverability, and /release. Writes use their wallet-authentication and ownership contracts. Never treat an available string, a cookie alone, or a submitted public key as authority to activate it.
Resolution and privacy
GET /.well-known/metanet-handles/resolve?handle=… accepts exactly one local handle parameter. The server normalizes case and strips a +tag; an embedded @, malformed label, duplicate parameter, or extra parameter is rejected. Reverse lookup and search live alongside it under /.well-known/metanet-handles and respect their discovery policy.
| Result | Meaning |
|---|---|
| 200 | Active binding with the required certificate, messagebox, and fresh revocation evidence |
| 400 | Malformed request/handle |
| 404 | No resolvable binding, including a reservation not yet activated |
| 410 | Revoked/released certificate binding; forwarding may be present |
| 429 | Rate limited |
| 503 | Disabled rollout or unavailable verification/dependency |
A 200 response includes metanetHandles, handle, domain, identityKey, certificate, messagebox, ttl, and revoked. Verify the certificate and current revocation evidence; an advisory cache TTL does not waive freshness for value-moving actions. Public revelation keys disclose their fields to everyone who receives them.
Messageboxes
The advertised base, when enabled, is /api/messagebox. The BRC-33-shaped endpoints are:
| Endpoint | Contract |
|---|---|
POST /sendMessage | Submit a signed envelope; recipient policy, toll, proof, and replay checks apply |
POST /listMessages | BRC-104 recipient authentication; { messageBox, limit?, after? } |
POST /acknowledgeMessage | BRC-104 recipient authentication; { messageIds: [...] } |
GET /toll | Inspect the supported recipient toll contract |
GET, POST /policy | Owner-authenticated policy management |
POST /policy/contacts | Owner-authenticated contact-policy changes |
These suffixes are relative to /api/messagebox, not /api/auth. Use the declared signed envelope contract; arbitrary chat JSON is not accepted as a valid message. The recipient for listing is derived from the authenticated wallet key, not a caller-selected account ID.
Listing returns messages with messageId, sender, and serialized envelope body, with a cursor when another page may exist. Pass that cursor as after. Acknowledgement accepts up to 100 message UUIDs. The host also supports the mutually exclusive { all: true, messageBox } form; use it only when the user deliberately wants to acknowledge the whole box.
Acknowledgement changes mailbox delivery state; it does not promise secure erasure of every retained copy. Do not assume all envelope content is end-to-end encrypted merely because the sender signed it. Disabled endpoints return unavailable errors instead of bypassing wallet proof or recipient policy.
Delegations
A handle, a team role, and a signed delegation convey different authority. See teams and agents. Revoking or releasing a binding does not reset an account, replace a key, or erase public history.