Prove your subnet's links

What a proof is

Anyone can type any URL into an on-chain identity or a README. A proof is a bittensor.json file that lists your links and is signed with your subnet owner coldkey. You publish it in your repo or on your website.

A link is verified only while its proof:

• names your subnet and its current registration,
• is signed by the coldkey it names,
• names the coldkey that owns the subnet now, and
• has not expired.

Proofs are checked about once a day. If a check fails (the file is gone, the owner coldkey changed, the proof expired), the link stops being verified.

What verified means

The subnet's owner coldkey signed, within the last 90 days, that this link belongs to the subnet.

What it doesn't mean

• It is not an endorsement by bittensor.ai.
• It says nothing about whether the site or the code is safe or any good.
• A link without a proof isn't fake: its owner just hasn't signed one.

Before you start

You need:

• your subnet's netuid;
• the block your subnet's current registration started at. The subnet's page shows it as the registration block; on chain it is SubtensorModule.NetworkRegisteredAt(netuid). Write it without separators;
• the subnet owner coldkey's SS58 address;
• the links you want verified;
• a wallet that holds that coldkey.

Nothing here asks for your seed, mnemonic or password. You sign in your own wallet.

The file

UTF-8 JSON, at most 16 KiB. One proof is an object with exactly these keys:

kind is one of repo, website, docs, blog, x, discord, telegram, huggingface, youtube, linkedin, other. It is your own label: links are matched by URL, not by kind.

Each link's URL:

• starts with https:// and has a host name: no IP address, no port, no user or password, no # fragment;
• is at most 512 characters of printable ASCII. Write an international domain name in its xn-- form;
• has no secrets in the query (token, access_token, signatures, X-Amz-*);
• appears only once.

Every text value is printable ASCII. Numbers are whole numbers. Duplicate keys make the file invalid.

An example, for netuid 12:

{
  "version": 1,
  "network": "finney",
  "netuid": 12,
  "network_registered_at": 4567890,
  "coldkey": "5CcyqxXnJucaCnQQvvUg5EPzj1uoNAxACZvzArHw5aVDvgNH",
  "links": [
    {"kind": "repo", "url": "https://github.com/acme/subnet"},
    {"kind": "website", "url": "https://acme.example/"},
    {"kind": "x", "url": "https://x.com/acme"}
  ],
  "issued_at": "2026-10-01T00:00:00Z",
  "expires_at": "2026-12-30T00:00:00Z",
  "signature": "0xc665bbe936848e767cc6035d4f116ed5d7569d9e2fc49e3fa3e9b3791dc3d24a51c707aa734b4a95d6e134324a32dc4b45e1b5bed135b949a69f544b64ab2388"
}

This example is valid for exactly 90 days, the maximum. Its coldkey is a public test key: never send funds to it.

Own several subnets? Put up to 16 proofs in one file, at most one per subnet: {"proofs": [<proof>, …]}.

Where to publish it

Either place, or both. Each is checked on its own.

In your repo

• bittensor.json at the root of the default branch of a repo linked to your subnet, such as the GitHub repo in its on-chain identity. Other branches and tags are not read.
• A regular file: not a symlink, a submodule or a folder.
• At most 16 KiB.

On your website

• https://<host>/.well-known/bittensor.json, where <host> is the host of the website in your subnet's on-chain identity.
• Only that exact URL is read: https, port 443, no query. URLs inside the proof are never fetched.
• Redirects may go only to the same path on the same host or its www. twin (example.com and www.example.com), https on every hop.
• Serve it as application/json (text/plain and application/octet-stream work too), at most 16 KiB, and let robots.txt allow it.

The published file can be pretty-printed, with its keys in any order: the message is rebuilt from the values.

The message you sign

The coldkey signs one line of ASCII: bittensor-ownership-proof:v1: followed by the proof without its signature key, written as JSON this way:

• keys sorted alphabetically, at every level, including inside each link;
• no whitespace at all: , and : with no spaces, no line breaks;
• arrays kept in your order (the links are not sorted);
• no newline at the end.

In Python that is json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=True). The bytes signed are the message's ASCII bytes. Nothing is hashed first.

The message for the example above:

bittensor-ownership-proof:v1:{"coldkey":"5CcyqxXnJucaCnQQvvUg5EPzj1uoNAxACZvzArHw5aVDvgNH","expires_at":"2026-12-30T00:00:00Z","issued_at":"2026-10-01T00:00:00Z","links":[{"kind":"repo","url":"https://github.com/acme/subnet"},{"kind":"website","url":"https://acme.example/"},{"kind":"x","url":"https://x.com/acme"}],"netuid":12,"network":"finney","network_registered_at":4567890,"version":1}

Its sha256 is 515296b85818a29e482d00906962978086a42888640585855f24e22025082d87. Build the same message from the example to check your own code.

Two forms of signature are accepted: over the message as it is, or over <Bytes> + message + </Bytes>, which is what wallet extensions sign. sr25519 signatures are randomised: signing twice gives two different signatures, both valid.

Sign it

Build the message with the offline builder

The builder is a single HTML file you download and open from your own computer. It makes no network calls and never asks for a key. Enter the netuid, the registration block, the coldkey address and your links, and choose a lifetime of 1 to 90 days. It checks the rules above, shows the message to sign and its hex, and writes bittensor.json once you paste the signature back.

Download the proof builder (ownership-proof.html)

Then sign the message with the subnet owner coldkey, in one of these ways.

btcli

--no-use-hotkey signs with the coldkey. Put the message between '<Bytes> and </Bytes>', in single quotes. For the example:

btcli wallet sign --wallet-name <owner wallet> --no-use-hotkey --json-output --message '<Bytes>bittensor-ownership-proof:v1:{"coldkey":"5CcyqxXnJucaCnQQvvUg5EPzj1uoNAxACZvzArHw5aVDvgNH","expires_at":"2026-12-30T00:00:00Z","issued_at":"2026-10-01T00:00:00Z","links":[{"kind":"repo","url":"https://github.com/acme/subnet"},{"kind":"website","url":"https://acme.example/"},{"kind":"x","url":"https://x.com/acme"}],"netuid":12,"network":"finney","network_registered_at":4567890,"version":1}</Bytes>'

btcli asks for the coldkey password itself. Copy signed_message from its output as one line (the terminal may wrap it), with 0x in front. A link that contains a single quote can't be passed this way.

Python

With bittensor-wallet or substrate-interface, which both have Keypair.sign:

import json
from bittensor_wallet import Wallet  # or: from substrateinterface import Keypair

payload = {...}  # every key of the proof except "signature"
message = "bittensor-ownership-proof:v1:" + json.dumps(
    payload, sort_keys=True, separators=(",", ":"), ensure_ascii=True
)
coldkey = Wallet(name="owner").coldkey  # asks for the coldkey password
signature = "0x" + coldkey.sign(message.encode()).hex()
assert coldkey.verify(message.encode(), bytes.fromhex(signature[2:]))
with open("bittensor.json", "w") as f:
    json.dump({**payload, "signature": signature}, f, indent=2)

A wallet extension

1. Open polkadot.js Apps, then Developer, then Sign and verify.
2. Choose the coldkey account. Accounts from the polkadot.js extension, Talisman or SubWallet are listed there.
3. Paste the message exactly (or its 0x hex), choose Sign, and approve in the wallet.

The extension signs <Bytes>message</Bytes>, which is accepted.

Check it before publishing

The builder can't check signatures, so check the file before you publish it. A file that does not check out must not be published. Either:

• the signature verifier on bittensor.ai, or polkadot.js Apps (Developer, Sign and verify, Verify): the message, the coldkey address and the signature must show as valid;
• or Python:

import json
from substrateinterface import Keypair  # or: from bittensor_wallet import Keypair

doc = json.load(open("bittensor.json"))  # a single proof (for a bundle, check each entry of "proofs")
signature = doc.pop("signature")
message = b"bittensor-ownership-proof:v1:" + json.dumps(
    doc, sort_keys=True, separators=(",", ":"), ensure_ascii=True
).encode()
print(Keypair(ss58_address=doc["coldkey"]).verify(message, signature))  # must print True

A signature from another key, a hotkey, or over a different or edited message (a trailing newline included) does not check out. Make sure the coldkey owns the subnet now (btcli subnet list, or the subnet's page).

Rules

• Mainnet only. network is finney; any other network is invalid (bad_network).
• At most 90 days. expires_at is no more than 90 days after issued_at. Re-sign at least that often.
• The owner coldkey only. A proof signed by a hotkey does not verify.
• The current registration only. A netuid can be registered again by someone else. A proof names one registration (netuid and network_registered_at), and only the current one is checked.

Check results

Each place (repo, website) gets one result per check:

verified

The proof checks out. Its links show as verified.

What to do: Nothing, until it nears expires_at. Re-sign before then.

not_found

There is no file at that place.

What to do: Put bittensor.json at the root of the repo's default branch, or serve it at https://<your site>/.well-known/bittensor.json.

fetch_failed

The file could not be read: the site did not answer, a certificate or server error, robots.txt blocks it, or a redirect went somewhere else.

What to do: Make the URL load over https, allow it in robots.txt, and redirect only to the same path on the same host or its www twin.

malformed

The file is over 16 KiB, not JSON, or breaks a rule above: a missing or extra key, a bad link, a lifetime over 90 days.

What to do: Rebuild it with the builder. Two reasons have their own name: bad_network (the network is not finney) and not_yet_valid (issued_at is more than 5 minutes in the future).

wrong_life

The file has no proof for this subnet's current registration: another netuid, or the block of an earlier registration.

What to do: Check netuid and network_registered_at, and sign a new proof.

bad_signature

The signature does not match the coldkey the proof names.

What to do: Sign the exact message with that coldkey, not a hotkey. Sign it again after any change to the file, and check it before publishing.

wrong_coldkey

The proof's coldkey is not the subnet's owner coldkey now.

What to do: Sign a new proof with the current owner coldkey. This is expected after a coldkey swap or a change of owner.

expired

expires_at has passed.

What to do: Sign a new proof (at most 90 days).

Renew

• Re-sign before expires_at, at most every 90 days, and replace the file.
• After a coldkey swap or a change of owner, the new owner coldkey must sign a new proof. The old one stops verifying at the next check.
• A proof copied somewhere else still only covers the links and subnet it names.