Subnet services

A validator (a hotkey with a validator permit on a subnet) or the subnet owner, for its owner hotkey, can publish a service with set-service, so that apps and agents can find what the subnet serves and how it is paid for. A service is a url to a document of its services and the spender its customers name on gamma deposits. The coldkey that owns the hotkey signs it, names the spender, and pays a normal fee. Publishing an empty url removes the service.

btcli tx set-service --netuid 51 --url https://example.com/services.json -w my_coldkey -H my_hotkey
btcli query services --netuid 51

await client.execute(bt.SetService(netuid=51, url="https://example.com/services.json"), wallet)
services = await client.subnets.services(netuid=51)  # {hotkey: {url, spender, owner}}

The permit is checked when the service is published. A service follows a hotkey swap and is removed when its neuron is deregistered. A coldkey swap leaves its spender, and changing the spender leaves deposits that name the old one until their coldkeys re-point them. owner marks the service of the subnet owner's hotkey while the owner owns it, whose spender new deposits name by default. A leased subnet's beneficiary publishes it through its SubnetLeaseBeneficiary proxy. Customers name a service's spender by minting with --service-hotkey (see Gamma).

The document

The chain stores the url and the spender. The document says what the services are, how to reach them, and how they are paid for:

{
  "version": 1,
  "services": [
    { "type": "openapi", "endpoint": "https://…", "spec": "https://…/openapi.json" },
    { "type": "mcp", "endpoint": "https://…/mcp" }
  ],
  "payments": [
    { "type": "gamma" },
    { "type": "x402" }
  ]
}

• A gamma payment accepts the subnet's gamma, from deposits that name the service's spender.
• An x402 payment states its price and payee in each HTTP 402 response.
• Readers skip service and payment types they do not know.

A service can name any spender, and that spender can spend the deposits that name it without serving, so prefer the service marked owner.

While a spender's coldkey swap is announced, it cannot spend. A service that must never pause names a spender that never needs a swap, such as a multisig of several keys, and spends through a separate GammaSpend key, which the spender itself replaces by changing the proxy. A pure proxy is not such a spender, as the coldkey that controls it keeps that control through its own coldkey swap, so a leaked coldkey would keep spending.