Subnet-6 miners and validators authenticate with Desearch APIs using cryptographic signatures. This page covers coldkey linking and request authentication for both roles.
Miners
Connect a Miner's Coldkey to a Desearch Account
Before a Subnet-6 miner can use Desearch APIs, their coldkey must be cryptographically linked to their Desearch account. This proves ownership and authorizes all miners (hotkeys) that belong to that coldkey.
Prerequisites
- Register at: https://console.desearch.ai
- Generate a Desearch API Key
- Have your Bittensor coldkey wallet available
How It Works
- You sign your Desearch API key with your coldkey
- Desearch verifies the signature against the coldkey's public SS58 address
- This links the coldkey to your account
- After linking, you can generate new API keys. The coldkey stays attached to the account
- To move the coldkey to another account, run the script again with that account's API key
Linking Miner's Coldkey to Desearch (One-time)
import requests
from bittensor_wallet import Wallet
API_KEY = "DESEARCH_API_KEY"
WALLET_NAME = "my_wallet"
WALLET_PASSWORD = "my_password"
# Load Bittensor wallet and coldkey
wallet = Wallet(name=WALLET_NAME)
keypair = wallet.get_coldkey(WALLET_PASSWORD)
coldkey_ss58 = keypair.ss58_address
print(f"Using coldkey: {coldkey_ss58}")
# Sign the Desearch API key with your coldkey private key
signature_bytes = keypair.sign(API_KEY.encode("utf-8"))
signature_hex = signature_bytes.hex()
# Preferred form: raw key in Authorization, without a Bearer prefix.
headers = {
"Authorization": API_KEY,
"Content-Type": "application/json",
}
payload = {
"coldkey_ss58": coldkey_ss58,
"signature_hex": signature_hex,
}
url = "https://api.desearch.ai/bt/miner/link"
print("Linking miner to Desearch account...")
response = requests.post(url, json=payload, headers=headers)
print(f"\nResponse from /bt/miner/link [{response.status_code}]:")
print(response.text)
Authenticating Requests as a Subnet-6 Miner
Miners sign the code with their hotkey and send the signature back to the validator.
from bittensor_wallet import Wallet
# Load bittensor wallet
wallet = Wallet(name="my_wallet", hotkey="default")
CODE = "SIGNING_CODE_HERE"
# Sign code with hotkey
keypair = wallet.get_hotkey()
signature_bytes = keypair.sign(CODE.encode("utf-8"))
signature_hex = signature_bytes.hex()
print(f"Signature (hex): {signature_hex}\n")
Send the signature back to the validator along with the code.
Validators
Authenticating Desearch Requests as a Validator
Validators authenticate themselves and forward miner credentials when calling Desearch APIs.
To authenticate as a validator, sign the current timestamp with your validator hotkey and include it in the request headers.
from datetime import datetime, timezone
from bittensor_wallet import Wallet
# Sign timestamp with validator hotkey
wallet = Wallet(name="validator", hotkey="default")
keypair = wallet.get_hotkey()
validator_timestamp = datetime.now(timezone.utc).isoformat()
validator_signature = keypair.sign(validator_timestamp.encode("utf-8")).hex()
validator_hotkey = keypair.ss58_address
headers = {
"X-Validator-Hotkey": validator_hotkey,
"X-Validator-Signature": validator_signature,
"X-Validator-Timestamp": validator_timestamp,
# Forward miner signature info
"X-Miner-Signature": 'signature',
"X-Miner-Code": 'code',
"X-Miner-Hotkey": 'hotkey',
"X-Miner-Coldkey": 'coldkey',
}
response = requests.get(
"https://api.desearch.ai/twitter",
headers=headers,
params={"query": "crypto", "sort": "Top", "count": 20},
)
print(response.status_code, response.text)
Timestamp Validation
Validator timestamps must be:
- In ISO 8601 format with timezone (UTC)
- Within ±5 minutes of the current time
- Unique per request
What Desearch Verifies
For every API request, Desearch checks:
-
Validator Authentication
- Validator hotkey is whitelisted in the subnet
- Validator signature matches the timestamp
- Timestamp is within 5 minutes
-
Miner Authentication
- Miner signature is valid for the provided code
- Miner's coldkey is linked to a Desearch account
- Miner's hotkey belongs to the linked coldkey