Sats Names

Protocol Spec

New names can be registered (inscribed for the first time) as ordinals with only a Bitcoin transaction. This process is open to anyone that can write to Bitcoin.

Registering names

Simple registration

To register a new name within the Sats Name System simply inscribe an ordinal containing your desired name. Here is an example.

Advanced registration

Advanced registration allows users to additional data to a name using JSON5 syntax. The format is optional for registration. It will be required for update operations. Here is an example.
"p": "sns",
"op": "reg",
"name": "helloworld.sats",
Protocol: Helps other systems identify and process SNS names
Operation: Helps indexers compute name state
Name: Your desired name. Including .sats is required.

Registration limitations

These apply to both registration types:
  • Only one name per ordinal
  • Any UTF-8 character is valid
  • Capitalization does not matter. All names will be registered as lowercase.
  • No spaces are permitted within a name

Building an indexer

These instructions explain the protocol logic and instructions for extracting and validating names so you can properly index them and determine the first instanace of each name.

Fetch the data

These instructions assume you have access to the entire ordinals data structure with basic details like content type, ID, as well as the content. To materialize Sats Names correctly you must index all ordinals back to inscription number 159710.
Validate that the inscription's content type is any of these:
  • text/plain
  • application/json
Fetch text as the raw text contents of an inscription. For example, text would be the raw contents returned at this URL.

Validate names

The first instance of each name is the only valid instance of the name in the Sats Name System. We determine which name is first by inscription number. The following instructions will tell you how to extract and validate the name so you can compare inscription number and determine the first.

Extracting the name from JSON5

  1. 1.
    Validate if the text is valid JSON according to the JSON5 standard. To check if the inscription is JSON, try parsing the text. If an error is thrown (invalid JSON), skip to the "plain text" instructions listed under Validate Names.
  2. 2.
    Check that the JSON has the required properties:
    • p equals "sns"
    • op equals "reg"
    • name is present and is of type string
  3. 3.
    Once name is extracted, follow the steps proceed to the Validate names steps.
Trailing commas are valid in JSON5. New lines inside values are not valid.

Validate names

  1. 1.
    Turn the string into lowercase
  2. 2.
    Delete everything after the first whitespace or newline (\n)
  3. 3.
    Trim all whitespace and newlines
  4. 4.
    Validate that there is only one period (.) in the name
  5. 5.
    Validate that the string ends with .sats

Indexer & API

If you have a valid .sats name compare all other instances of the same name. The first instance of the name according to inscription number is the only valid Sats Name, or "first" of this name.
Make sure you convert all queries to lowercase, otherwise you might inadvertently show name as available when they are registered.
Make sure your API returns a decoded version of the UTF-8 name. Scammers hide hidden characters inside names and by including this information clients can flag deceptive names.


Queries for names that include # and ? will fail unless you convert them to URL encoding reference first.