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. 
satoshi.sats
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",
}
Key
Required?
Description
p
Yes
Protocol: Helps other systems identify and process SNS names
op
Yes
Operation: Helps indexers compute name state
name
Yes
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 Ordinals.com 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.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.Check that the JSON has the required properties:
p equals "sns"
op equals "reg"
name is present and is of type string
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.Turn the string into lowercase
2.Delete everything after the first whitespace or newline (\n)
3.Trim all whitespace and newlines
4.Validate that there is only one period (.) in the name
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. 
Clients
Queries for names that include # and ? will fail unless you convert them to URL encoding reference first. 
​

Key	Required?	Description
p	Yes	Protocol: Helps other systems identify and process SNS names
op	Yes	Operation: Helps indexers compute name state
name	Yes	Name: Your desired name. Including .sats is required.

Last modified 2mo ago