AT Protocol (atproto)

A guide for building on atproto -- the protocol behind Bluesky and the broader atmosphere of interoperable apps. This file is the overview and a router; deep details live in references/.

Mental model

atproto is a federated protocol where users own a signed, content-addressed data repository that any service can replicate. Apps are mostly app views -- services that consume the network firehose, validate records against a Lexicon schema, index them, and expose a read API. Writes go to the user's PDS via XRPC.

Five concepts to keep in your head:

• DIDs identify accounts permanently (did:plc:... or did:web:...).
• Handles are mutable, DNS-based usernames.
• Repositories are signed, content-addressed Merkle Search Trees of records held on a PDS.
• Lexicons are JSON schemas naming and validating records and HTTP endpoints, addressed by NSID (com.example.fooBar).
• XRPC is HTTP transport for Lexicon-defined endpoints; the firehose is the WebSocket variant.

Service roles

Real systems are made of four roles. An app you build is usually #3.